BonkerBot 🔨

An open-source Discord scam filter with global reputation scoring, OCR on images, pattern learning, and community-driven training.

"Because Discord won't do jack shit."

Running your own instance

This repository is the bot: commands, moderation flows, scoring, the trust score maths, appeals, audit logging, retention. Everything that decides what happens to a person is here and auditable.

What is not here is the scam pattern library. A published detection list is a bypass checklist, so ours stays private. Two consequences for self-hosting:

• Bring your own patterns. A fresh instance starts with no detection rules. The training tools are included; the rules are not.
• You are not on the trust network. A self-hosted instance cannot read or write the global reputation scores. We have no way to verify what an instance we do not operate reports to us — the code is modifiable by definition, so accepting that data would let anyone poison reputations network-wide. Your instance keeps its own local scores instead.

Full reasoning: https://bonkerbot.app/docs/open-source

Features

🔍 Multi-Layer Scam Detection

• Text Analysis — Pattern-matching engine with rules for phishing, crypto scams, fake services, impersonation, urgency tactics, malware links, and more
• Link Analysis — URL extraction, blocked domain lists, typosquatting detection (Levenshtein distance), phishing domain patterns
• Image OCR — Tesseract.js-powered OCR with sharp preprocessing, detects scam text in screenshot/image-based scams
• Perceptual Image Hashing — Same scam image detected instantly across all servers after first confirmation

📊 Global Trust Scoring

• Every user gets a trust score from 0.0 to 10.0
• Scores follow users across all BonkerBot-protected servers
• Velocity-capped adjustments prevent abuse (max -3.0/24h from automation)
• Trust score history with graph visualization

🎯 Right-Click Reporting

• Context menu "Report Message" — any user can report suspicious messages
• Rate-limited to prevent abuse (3 reports per 10 minutes)
• Reports enriched with automated detection results
• Mod review embeds with Confirm/Dismiss/Escalate/Add Note buttons

🧠 Community Training System

• Core Trainers (owner-appointed) — submissions auto-accepted, full trust
• Loose Trainers (500+ member server owners) — submissions reviewed before acceptance
• Pattern extraction from confirmed scams (keywords, n-grams, URLs)
• 📖 See the Training Guide for a walkthrough on training the bot to detect AI scams and other emerging patterns

🔨 Auto-Actions

• Configurable per-server thresholds for warn/mute/kick/ban
• Actions logged with undo buttons for moderators
• Emergency pause (kill switch) to disable all auto-actions instantly

📈 Campaign Detection

• Clusters similar scam reports into campaigns
• Tracks involved users and affected servers
• Auto-resolves stale campaigns

🛡️ Additional Features

• Honeypot channel detection (scam bots posting in trap channels)
• Join-spam detection (multiple new accounts joining rapidly)
• Low-trust join alerts for moderators
• Channel allowlists (skip scanning in trusted channels)
• Trend monitoring and alert system
• Full audit logging
• Privacy-first: data export and deletion via /privacy

Tech Stack

Component	Technology
Runtime	Node.js 20+ (ESM)
Language	TypeScript (strict)
Discord	discord.js v14
Database	PostgreSQL + Prisma ORM
OCR	tesseract.js + sharp
Charts	chartjs-node-canvas
Typosquat	fastest-levenshtein
Image Hash	imghash
API	Express (health/metrics)
Logging	pino
Testing	vitest
CI/CD	GitHub Actions → SSH/rsync → pm2

Setup

Prerequisites

• Node.js 20+
• PostgreSQL 14+
• A Discord bot application with:
  • MESSAGE_CONTENT privileged intent
  • GUILD_MEMBERS privileged intent
  • applications.commands scope

Installation

git clone https://github.com/Orange-Cat-Associated/BonkerBot.git
cd BonkerBot
npm install
cp .env.example .env
# Edit .env with your values

Database Setup

npx prisma generate
npx prisma migrate dev
npm run db:seed   # Optional: seed blocked domains

Running

# Development
npm run dev

# Production
npm run build
npm start

# Deploy commands to Discord
npm run deploy:commands

# With pm2
pm2 start ecosystem.config.cjs

Required Bot Permissions

Send Messages
Embed Links
Attach Files
Read Message History
Moderate Members (timeout)
Kick Members
Ban Members
Use Application Commands

Discord Developer Portal Setup

1. Create a new application at discord.com/developers
2. Go to Bot → Enable MESSAGE CONTENT INTENT and SERVER MEMBERS INTENT
3. Go to OAuth2 → URL Generator → Select bot + applications.commands
4. Select the permissions listed above
5. Use the generated URL to invite the bot

Commands

Full reference: bonkerbot.app/docs/commands

Slash Commands

Command	Description	Permission
/help	Command and feature reference, in-channel	Everyone
/karma [user]	Global Karma (trust) score and history	Everyone (self) / Moderator (others)
/appeal	Submit a ban appeal, or check its status	Everyone (list is Moderator)
/privacy	View privacy policy, export/delete data	Everyone
/scoreboard	Lowest-Karma users in the server	Moderator
/stats	Scam detection statistics for the server	Moderator
/setup-server	Guided setup, and targeted re-configuration	Admin
/botconfig	Channels, roles, modules, thresholds, tuning	Admin
/admin	Bot administration (admin guild only)	Bot Admin
/setup-admin-guild	One-time admin guild channel creation	Bot Admin
/youtube-auth	YouTube OAuth2 for transcript access	Bot Admin
/youtube-train	Extract scam patterns from YouTube videos	Bot Admin

Context Menus (Right-Click)

Command	Description	Permission
Report Message	Report a suspicious message	Everyone
Train as Scam	Submit a message as a scam sample	Trainer

Environment Variables

See .env.example for all available configuration options.

Deployment

The bot is designed for bare-metal deployment with pm2 and GitHub Actions CI/CD.

See .github/workflows/deploy.yml for the CI/CD pipeline.

GitHub Secrets Required

• DEPLOY_HOST — Server hostname/IP
• DEPLOY_USER — SSH username
• DEPLOY_KEY — SSH private key
• DEPLOY_PATH — Absolute path on server (e.g., /home/bonkerbot/app)

License

MIT — see LICENSE for details.

Contributing

Contributions are welcome for the public half of the project — commands, UI and embeds, setup flows, database and performance work, tests, docs, bug fixes. Please open an issue first to discuss what you would like to change.

Detection patterns cannot be accepted as public contributions: a scam rule that arrives in a public pull request has already been published by the time anyone reviews it. Those go through a private review path instead.