The ultimate open-source, proactive security shield for Discord servers.
Continuously collects phishing feeds, scans text and images using local OCR, instantly deletes malicious threats, and empowers server administrators with dynamic multilingual actions.
Quick Start · Core Features · Interactive Setup · How It Works · Architecture · API Quotas
- What is PhishGuard?
- ✨ Core Features
- ⚙️ Interactive Setup
- 📦 Project Structure
- 🚀 Quick Start
- ⚡ How It Works
- 🏗️ System Architecture
- 📡 Threat Intelligence Sources
- 📊 API Keys & Rate Limits
- 💬 Dynamic Embed Layouts
- 🤝 Contributing
- 📜 License
PhishGuard is a state-of-the-art Discord bot designed to continuously safeguard your gaming, crypto, and community servers from phishing campaigns, token loggers, and social engineering giveaway scams.
Unlike traditional, reactive logging systems, PhishGuard operates autonomously in real-time. It monitors user messages and image attachments, cross-checks links against multiple industry-leading threat intelligence feeds, utilizes a localized optical character recognition (OCR) engine, and instantly mitigates verified threats before your users can click them.
- Zero-Day Screenshot Detection: Scammers frequently post screenshots (e.g., fake Twitter/X posts from influencers like MrBeast, giveaway QR codes, or free Nitro banners) instead of text to bypass bot filters.
- Tesseract.js Integration: Integrates a local OCR engine to parse image attachments (
.png,.jpg,.jpeg,.webp), extract textual data, and instantly scan it for phishing templates, malicious URLs, and high-frequency scam keywords.
- Automatic Deletion: As soon as a text message or image attachment is classified as high-risk, the bot deletes the message instantly from the chat, protecting users from accidental exposure.
- Self-Destruct Warning Cards: Replaces the deleted threat with a polished, compact coral-colored warning card (
#FFA07A) notifying the channel. To keep chats visually clean, this card automatically deletes itself after 30 seconds.
- User Action Buttons: The public warning card includes interactive buttons that provide a beautiful, non-intrusive response:
❓ Why was this deleted?: Sends an ephemeral popup (visible only to the sender) explaining that their message matched known malicious pattern signatures.💡 Security Tips: Generates an ephemeral safety checklist instructing the user on how to enable 2FA, audit active Discord sessions, revoke unrecognized authorized apps, and recognize QR code login scams.
- Compact Executive Audit Logs: Saves server layout space by aggregating extensive audit reports into compact, bulleted summary widgets inside the designated administrative channel, reducing visual footprint by over 85%.
- One-Click Moderator Actions: Administrative alert logs feature real-time moderator control buttons:
✅ False Positive: Instantly whitelists the flagged resource in the SQLite database, transitions the warning card to emerald green, and disables buttons live.🔨 Ban User: Bypasses complex Discord moderation steps, allowing admins to instantly ban the compromised account with a secure audit reason trail.
- Localization Matrix: Out-of-the-box support for English, Spanish, and Portuguese.
- Guild-Specific Locale Routing: Automatically translates command outputs, warning popups, buttons, audit logs, and explanations dynamically on a per-guild basis.
Deploying and configuring PhishGuard takes seconds with its built-in interactive slash commands, bypassing traditional Discord guild propagation delays.
Allows administrators to customize bot settings dynamically.
/setup [logs_channel: #channel] [language: English/Español/Português]
logs_channel: Designates where the executive moderation alert reports and actions will be routed. Falls back to.envconfigurations if not provided.language: Sets the language context (en,es,pt) for the entire server.- Access Control: Strict guardrails ensure only members with Administrator or Manage Guild permissions can execute setups.
- Persistence: Server-specific variables are saved directly to a lightweight SQLite database, allowing seamless restarts.
PhishGuard implements a modular, clean, and highly maintainable architecture adhering to TypeScript best practices:
phishguard-bot/
├── src/
│ ├── core/ # System Foundation
│ │ ├── commandDeployer.ts # Instant slash command deployment routes
│ │ ├── config.ts # Environment strict validation & schema
│ │ ├── database.ts # SQLite database manager (better-sqlite3)
│ │ └── types.ts # Globally shared TypeScript interfaces
│ │
│ ├── services/ # Business Logic Core
│ │ ├── apiScanner.ts # VirusTotal, PhishTank, & Sinking Yachts connectors
│ │ ├── feedManager.ts # Large-scale database threat collectors
│ │ ├── notificationService.ts # Rich high-fidelity UI embed engines
│ │ ├── scamDetector.ts # Regular expression threat classification signature
│ │ ├── scamHandler.ts # Message filter coordinator & OCR parser
│ │ └── twitterMonitor.ts # Stateless social monitor for Twitter/X feeds
│ │
│ ├── utils/ # Auxiliary Utilities
│ │ ├── i18n.ts # Multi-language translation matrix & helpers
│ │ └── urlHelper.ts # Domain extractor, normalizer, and regex
│ │
│ └── index.ts # Main orchestrator & listener bootstrap
│
├── ARCHITECTURE.md # Comprehensive architectural blueprints
├── LICENSE # MIT License details
├── package.json # Dependency manifests & scripts
├── tsconfig.json # Compiler configurations
└── phishguard.db # persistent SQLite cache file (auto-generated)
- Node.js v20.0.0+
- pnpm v9.0.0+ (Install globally via
npm i -g pnpm) - SQLite3 (Compatible with better-sqlite3)
- A Discord Bot Account (Obtained through the Discord Developer Portal)
-
Clone the repository:
git clone https://github.com/AxthonyV/PhishGuard-Bot.git cd PhishGuard-Bot -
Install dependencies:
pnpm install
Create a .env file in the root directory by copying the template:
cp .env.example .envOpen .env and fill in your keys:
# ── Required ───────────────────────────────────────────────────────────────────
# Your Discord Bot Token (Developer Portal -> Application -> Bot -> Token)
DISCORD_TOKEN=your_bot_token_here
# Default fallback log channel ID (if `/setup` is not used in a guild)
REPORT_CHANNEL_ID=1234567890123456789
# VirusTotal API Key for real-time link verification (500 free queries/day)
VIRUSTOTAL_API_KEY=your_virustotal_key_here
# ── Optional ───────────────────────────────────────────────────────────────────
# PhishTank API Key (Increases request limit quotas, works without key)
PHISHTANK_API_KEY=your_phishtank_key_here
# Twitter/X Bearer Token (Enables watching cybersecurity feeds for links)
TWITTER_BEARER_TOKEN=your_twitter_bearer_token_here
# Default system locale fallback (Options: en, es, pt)
LOCALE=enDiscord Developer Portal Settings: Under your Bot configurations page, ensure Message Content Intent is enabled under the Privileged Gateway Intents section, otherwise the bot will be unable to intercept chat threats!
pnpm devpnpm build
pnpm startPhishGuard coordinates multiple continuous pipelines to keep your servers safe:
graph TD
A[Incoming Discord Message / Attachment] --> B{Has Image Attachment?}
B -- Yes --> C[Run Tesseract OCR Image Scan]
B -- No --> D{Contains URL?}
C --> E[Extract Text & Hidden URLs]
E --> D
D -- Yes --> F{Check SQLite Cache}
D -- No --> Z[Allow Message]
F -- Threat Cached --> G[Instant Mitigation Deletion & Warning]
F -- Cache Miss --> H[Query VirusTotal API]
H -- Flagged Phishing --> I[Query PhishTank Secondary Verification]
I --> J[Save to SQLite DB & Trigger Deletion]
H -- Clean Link --> Z
style G fill:#ff7b7b,stroke:#333,stroke-width:2px
style Z fill:#a1ffa1,stroke:#333,stroke-width:2px
- User sends a message or uploads an image.
- The
scamHandlerintercepts the payload. If an image exists, Tesseract OCR processes it, converting visual writing to plain text and extracting embedded URLs.
- SQLite Cache Query: Checks if the URL has already been classified to avoid consuming third-party API quotas.
- VirusTotal API Scanning: The primary verification gate. Submits URLs using Base64URL tags.
- PhishTank Check: If flagged by VT, it cross-references PhishTank to gather full community verification indices (ID, status).
- Sinking Yachts Check: Domain-level resolution for specialized Discord nitro hacks or Steam phishing.
- Deletes the source message.
- Dispatches the ephemeral user safety panels and the self-destruct warning card.
- Logs the incident to the audit channel for moderator review.
PhishGuard is developed strictly following SOLID software development principles to ensure scalability and loose coupling:
- Modular Decoupling: API integrations (
apiScanner.ts), scheduling collections (feedManager.ts), database writes (database.ts), and localized messaging (i18n.ts) are structured as isolated single-purpose modules. - Local Failure Containment: Network errors, rate limits, or API outages from external providers are handled individually. The bot will automatically isolate the fault (e.g., fallback to secondary feed parsing) without crashing the main thread.
- Persistent Caching: State details are kept completely in SQLite (
phishguard.db) across two core tables:urls: Caches scanned resources, classification, severity scores, and audit tags.guild_configs: Stores locale preference and administrative channel routes by Guild ID.
PhishGuard imports and parses thousands of fresh threat records constantly:
| Resource | Feed Type | Frequency | Specialization |
|---|---|---|---|
| Phishing.Database | Plain-text URL list | Daily | Global bank, e-commerce, and wallet scams |
| OpenPhish | Clean text URL stream | Every 6 hours | Active credential harvest campaigns |
| VirusTotal API | Multi-engine cloud scan | Real-time | Cross-analyzes across 70+ security scanners |
| PhishTank | Community reports API | Real-time | Human-verified community classifications |
| Sinking Yachts | REST Endpoint | Real-time | Discord Nitro hacks & Steam stealer domains |
| Twitter/X Monitor | Live account streams | Every 30 min | Captures zero-day campaigns tweeted by researchers |
PhishGuard is designed to operate 100% free of charge, implementing smart queuing algorithms to stay within free-tier API parameters:
- VirusTotal Free Quota: Standard accounts get 4 requests/min, 500 requests/day.
- Smart Waiting Queue: The bot processes feed checks sequentially, sleeping 15 seconds between VT scans to guarantee a rate of exactly 4 requests/minute.
- Persistent caching: When a URL is scanned once, its status is stored forever. It will never request the external API for that URL again, saving extensive daily quotas.
- Discord rate limits: Enforces a brief message buffer (300ms) between audit logs to avoid API throttling during mass campaigns.
╔══════════════════════════════════════════════════════════╗
║ 🛡️ Channel Protected | Threat Neutralized ║
╠══════════════════════════════════════════════════════════╣
║ ║
║ 🚨 Security Alert: Suspicious message/image from ║
║ @AxthonyV was removed. ║
║ ║
╠══════════════════════════════════════════════════════════╣
║ [ ❓ Why was this deleted? ] [ 💡 Security Tips ] ║
╚══════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════╗
║ 🛡️ SECURITY CENTER | THREAT NEUTRALIZED ║
╠══════════════════════════════════════════════════════════╣
║ A suspicious threat was automatically intercepted in ║
║ #general. ║
║ ║
║ • 👤 Author: @AxthonyV (ID: 1506499773165) ║
║ • 🏷️ Detection: OCR Image Analysis Match ║
║ • 📊 Severity: 🔴 5 Detections ║
║ • 🔗 Flagged URL: https://deezwin.com/giveaway ║
║ • 📝 Original Message: "OMG free nitro deezwin.com!" ║
║ ║
╠══════════════════════════════════════════════════════════╣
║ [ ✅ False Positive ] [ 🔨 Ban User ] ║
╚══════════════════════════════════════════════════════════╝
Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project.
- Create your Feature Branch (
git checkout -b feature/AmazingFeature). - Commit your Changes (
git commit -m 'Add some AmazingFeature'). - Push to the Branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Make sure your code compiles perfectly with zero TypeScript errors by running pnpm build before submitting.
Distributed under the MIT License. See LICENSE for more information.
Keep your Discord communities safe, clean, and phishing-free.
Developed by AxthonyV (c) 2026