🛡️ SentinelBot — Telegram Moderation Bot for Web3 Communities

A production-ready, self-hosted Telegram group moderation bot built specifically for crypto/Web3 communities. Combines the best features from 10+ analyzed open-source bots into a single, configurable solution.

✨ Features

🔒 Anti-Spam & Scam Detection

• Pattern-based spam detection — 30+ crypto-specific spam patterns
• CAS integration — Combot Anti-Spam System checks against known spammer database
• Crypto scam detection — Wallet phishing, fake airdrops, seed phrase scams
• Crypto address spam — Detects unsolicited ETH/BTC/SOL/TRON addresses
• Phishing URL detection — Catches fake DEX, wallet, and DeFi sites
• Heuristic analysis — Excessive caps, emojis, repeated chars

🔑 Captcha Verification

• Math captcha — Solve a math problem to verify
• Button captcha — Tap the correct emoji
• Configurable timeout — Auto-kick if not solved in time
• Auto-restriction — New members can't post until verified

🔗 Link Filtering

• Whitelist mode — Only approved domains allowed
• Blacklist mode — Block specific domains
• URL shortener blocking — bit.ly, tinyurl, etc. auto-blocked
• Telegram invite filtering — Block group invite links
• Admin-configurable — Add/remove domains via commands

🌊 Flood Protection

• Rate limiting — Max messages per time window
• Duplicate detection — Blocks repeated identical messages
• Minimum interval — Prevents rapid-fire messages
• Configurable actions — Warn, mute, or ban

⚠️ Warning System

• Progressive warnings — 1st warn → 2nd mute → 3rd ban (configurable)
• Expiring warnings — Warnings auto-expire after 30 days
• Admin tracking — All warnings logged with reason and admin
• Self-check — Users can check their own warnings

📋 Audit Logging

• Database logging — Every moderation action recorded
• Channel logging — Optional Telegram channel for audit trail
• File logging — Application logs to data/sentinel.log
• Admin stats — View action statistics per chat

👋 Welcome System

• Customizable messages — Template variables ({mention}, {group_name}, etc.)
• Auto-delete — Join/leave messages auto-deleted
• Scam warnings — Built-in "admins never DM first" warning

---

🚀 Quick Start

Prerequisites

• Python 3.10+ (or Docker)
• A Telegram Bot Token from @BotFather

1. Clone & Setup

git clone <your-repo-url>
cd telegram-mod-bot

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure

cp .env.example .env
nano .env  # or your editor of choice

Required settings:

BOT_TOKEN=your_bot_token_here
OWNER_ID=your_telegram_user_id

Optional but recommended:

LOG_CHANNEL_ID=-1001234567890  # Private channel for audit logs
ADMIN_IDS=123456789,987654321  # Additional admin IDs
CAS_ENABLED=true               # Combot Anti-Spam checking

3. Run

# Development (polling mode)
python -m bot.main

# Or with Docker
docker-compose up -d

4. Add to Your Group

1. Add the bot to your Telegram group
2. Promote it to admin with these permissions:
   • ✅ Delete messages
   • ✅ Ban users
   • ✅ Invite users (for captcha)
   • ✅ Restrict members
   • ✅ Pin messages (optional)
3. Send /help in the group to verify it's working

---

📋 Commands

User Commands

Command	Description
/help	Show all available commands
/rules	Show group rules
/report	Report a message (reply to it)
/mywarns	Check your warning count

Admin Commands

Command	Description
/ban [reason]	Ban a user (reply or ID)
/unban	Unban a user
/kick [reason]	Kick a user (can rejoin)
/mute [duration]	Mute a user (e.g., /mute 1h)
/unmute	Unmute a user
/warn [reason]	Warn a user
/warns	Check a user's warnings
/clearwarns	Clear a user's warnings
/purge [n]	Delete last n messages

Settings Commands (Admin)

Command	Description
/settings	View current moderation settings
/setcaptcha on|off	Toggle captcha verification
/setlinks on|off	Toggle link filtering
/addlink domain.com	Add domain to whitelist
/rmlink domain.com	Remove domain from whitelist

Owner Commands

Command	Description
/stats	View moderation statistics
/auditlog	View recent audit log entries

---

⚙️ Configuration

Environment Variables

Variable	Required	Default	Description
BOT_TOKEN	✅	—	Telegram bot token
OWNER_ID	✅	—	Your Telegram user ID
ADMIN_IDS	❌	—	Additional admin IDs (comma-separated)
LOG_CHANNEL_ID	❌	—	Channel ID for audit logs
DATABASE_URL	❌	SQLite	Database connection string
CAS_ENABLED	❌	true	Enable CAS spam checking
WEBHOOK_URL	❌	—	Webhook URL (production)
WEBHOOK_PORT	❌	8443	Webhook port
OPENAI_API_KEY	❌	—	OpenAI key for AI spam detection

Per-Group Configuration

Copy config/default_config.yaml and customize for each group. Place configs in data/groups/<group_id>.yaml.

Pre-configured Whitelisted Domains

The following domains are whitelisted by default:

• telegram.org, t.me
• github.com, twitter.com, x.com
• sonic.game, soniclabs.com
• ethereum.org, etherscan.io
• coingecko.com, coinmarketcap.com
• dexscreener.com, defillama.com

Modify in /config/settings.py or via /addlink and /rmlink commands.

---

🐳 Docker Deployment

Build and Run

# Build image
docker build -t sentinel-bot .

# Run with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Production Deployment (Webhook Mode)

For production, use webhook mode with a reverse proxy:

WEBHOOK_URL=https://your-domain.com
WEBHOOK_PORT=8443
WEBHOOK_PATH=/webhook

Nginx config example:

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /webhook {
        proxy_pass http://localhost:8443;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

VPS Deployment (systemd)

# Copy files to server
scp -r . user@server:/opt/sentinel-bot

# Create systemd service
sudo cat > /etc/systemd/system/sentinel-bot.service << 'EOF'
[Unit]
Description=SentinelBot Telegram Moderation
After=network.target

[Service]
Type=simple
User=sentinel
WorkingDirectory=/opt/sentinel-bot
ExecStart=/opt/sentinel-bot/.venv/bin/python -m bot.main
Restart=always
RestartSec=10
EnvironmentFile=/opt/sentinel-bot/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now sentinel-bot

---

🏗️ Architecture

telegram-mod-bot/
├── bot/
│   ├── main.py              # Entry point, handler registration
│   ├── handlers/
│   │   ├── commands.py       # All slash commands
│   │   ├── moderation.py     # Core message processing pipeline
│   │   ├── welcome.py        # New member handling & captcha
│   │   └── callbacks.py      # Inline button handlers
│   ├── filters/
│   │   ├── spam.py           # Pattern-based spam detection
│   │   ├── crypto_scam.py    # Crypto-specific scam detection
│   │   ├── links.py          # URL/domain filtering
│   │   └── flood.py          # Flood/rate limit detection
│   ├── services/
│   │   ├── cas.py            # CAS integration
│   │   ├── captcha_generator.py  # Captcha generation
│   │   └── audit_log.py      # Audit logging service
│   ├── database/
│   │   └── db.py             # SQLite database layer
│   └── utils/
│       ├── permissions.py    # Admin/owner permission checks
│       └── helpers.py        # Utility functions
├── config/
│   ├── settings.py           # Configuration management
│   └── default_config.yaml   # Per-group config template
├── data/                     # Runtime data (DB, logs)
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example

Moderation Pipeline

Every group message flows through this pipeline:

Message → Admin Check (skip) → Verified Check → Flood → Spam → Scam → Links → ✅ Pass
                                    ↓              ↓       ↓       ↓       ↓
                                  Delete         Mute    Warn+Del Ban+Del Warn+Del

---

🔧 Customization

Adding Custom Spam Patterns

Edit bot/filters/spam.py — add patterns to SPAM_PATTERNS:

SPAM_PATTERNS = [
    # Your custom patterns
    (r"(?i)your_regex_pattern_here", "Description"),
    ...
]

Adding Custom Scam Patterns

Edit bot/filters/crypto_scam.py — add to SCAM_PATTERNS:

SCAM_PATTERNS = [
    (re.compile(r'your_pattern'), "scam_type", "Description"),
    ...
]

Whitelisting Domains

Either edit config/settings.py or use commands:

/addlink sonic.game
/addlink soniclabs.com
/rmlink suspicious-site.xyz

---

📊 Compared To

This bot was designed by analyzing 10+ open-source Telegram moderation bots. See RESEARCH.md for the full analysis.

Feature	SentinelBot	tg-spam	JoinCaptcha	Samurai	Origin
Anti-Spam	✅	✅	❌	✅	✅
CAS Integration	✅	✅	❌	❌	❌
Captcha	✅	❌	✅	❌	❌
Crypto Scam Detection	✅	❌	❌	❌	Partial
Link Filter	✅	✅	✅	❌	✅
Flood Protection	✅	❌	❌	✅	❌
Warning System	✅	❌	❌	❌	❌
Audit Log	✅	✅	❌	✅	✅
Docker	✅	✅	✅	✅	✅
Lightweight (<100MB RAM)	✅	✅	✅	❌ (800MB)	✅

---

📜 License

MIT — Use freely for your Web3 community.

---

Built with ❤️ for the Web3 community.