Real-time phishing detection platform — REST API engine, React dashboard, and Telegram bot. Built by Ali AlEnezi.

PhishBOT is built as three independent layers: a detection engine, a REST API, and two client interfaces (web dashboard + Telegram bot).

Every scan passes through 5 sequential analysis layers, each contributing a numeric score. The final score determines the verdict.

Input (URL / Text / Email)
        │
        ▼
┌───────────────────────────┐
│  1. Allowlist Check        │  ← Trusted domains bypass all checks
├───────────────────────────┤
│  2. URL Structural         │  ← IP hosting, TLD, encoding, shorteners
│     Analysis               │    homograph attacks, subdomain depth
├───────────────────────────┤
│  3. Brand Impersonation    │  ← Levenshtein distance typosquat detection
│     (Typosquat Detection)  │    against 20+ major brands
├───────────────────────────┤
│  4. Text / Email Heuristics│  ← Urgency patterns, credential harvesting,
│                             │    generic salutations, embedded URLs
├───────────────────────────┤
│  5. Keyword DB Matching    │  ← User-managed keyword list with
│                             │    configurable severity weights
└───────────────────────────┘
        │
        ▼
   Score 0–100
        │
   ┌────┴─────────────────────────┐
   │  0–34   →  ✅ CLEAN          │
   │  35–69  →  ⚠  SUSPICIOUS     │
   │  70+    →  🚨 PHISHING       │
   └─────────────────────────────┘

The React dashboard runs at http://localhost:3000 and has 4 tabs.

Real-time health check of your detection activity.

The interactive analysis tool. Supports three input modes:

After scanning, the result panel shows:

• Verdict badge — colour-coded CLEAN / SUSPICIOUS / PHISHING
• Threat Score bar — visual 0–100 risk meter
• Threat Signals — each detection with its point contribution (🔴 high / 🟡 medium / 🟢 low)
• Matched Keywords — keywords from your database found in the input

Your threat intelligence library. Add, search, and delete keywords that the engine uses for matching.

Categories: credential · urgency · financial · brand-abuse · scam · general

Severity levels and their scoring impact:

The Hits counter tracks how many times each keyword triggered, letting you identify active threat patterns.

Full audit trail of every scan. Filter by verdict, expand any row to see the full signal breakdown for that scan, and paginate through history.

Connects to your backend API and scans in real time inside any Telegram chat.

When AUTO_SCAN=true (default), the bot automatically scans every message:

• Messages containing a URL → URL structural analysis
• Messages longer than 30 characters → text heuristic analysis

For phishing/suspicious results, inline buttons appear:

• 📋 Full Report — reference the scan ID in the web dashboard
• ✅ Mark Safe — dismiss the alert

PhishBOT/
├── backend/
│   ├── server.js         Express entry point, middleware, rate limiting
│   ├── db.js             SQLite schema, seed keywords, seed allowlist
│   ├── detector.js       Core detection engine
│   └── routes/
│       ├── scan.js       POST /api/scan, POST /api/scan/bulk
│       ├── keywords.js   GET/POST/PATCH/DELETE /api/keywords
│       ├── logs.js       GET /api/logs, GET /api/logs/summary
│       └── allowlist.js  GET/POST/DELETE /api/allowlist
├── frontend/src/App.jsx  React dashboard (4 tabs)
├── bot/bot.py            Telegram bot (python-telegram-bot v21)
├── docs/screenshots/     UI screenshots
├── docker-compose.yml    Full-stack deployment
└── .env.example          Configuration template

cd backend && npm install && node server.js
# → http://localhost:3001

cd frontend && npm install && npm start
# → http://localhost:3000

cp .env.example .env           # Edit: set TELEGRAM_TOKEN
cd bot && pip install -r requirements.txt
TELEGRAM_TOKEN=xxx API_BASE_URL=http://localhost:3001 python bot.py

cp .env.example .env
docker-compose up -d                        # API + Frontend
docker-compose --profile telegram up -d    # + Telegram bot

POST /api/scan
{ "input": "https://paypa1-secure.verify-login.tk", "type": "auto" }

{
  "verdict": "phishing",
  "score": 85,
  "signals": [
    { "signal": "Brand keyword \"paypal\" embedded in domain", "score": 30 },
    { "signal": "Suspicious TLD: .tk", "score": 25 }
  ],
  "matchedKw": ["verify your account"]
}

POST /api/keywords
{ "keyword": "verify your banking", "category": "financial", "severity": "critical" }

Bulk add:

POST /api/keywords
{ "keywords": [{ "keyword": "reset your pin", "severity": "high" }] }

• Rate limiting — 200 req/15 min global, 60 req/min on scan endpoint
• Helmet.js — HTTP security headers (CSP, HSTS, X-Frame-Options)
• CORS control — configurable via ALLOWED_ORIGIN
• Input sanitization — stripped and length-capped before processing
• Allowlist bypass — trusted domains skip detection to reduce false positives

Ali AlEnezi — @SiteQ8

Kuwait-based cybersecurity practitioner focused on security architecture, compliance frameworks, and offensive security tooling.

PhishBOT is an open-source defensive security tool. Use responsibly.