phishing-detector

🛡️ Phishing Detector

🇹🇷 Adım adım detaylı Türkçe rehber → KURULUM.md
Türkçe → hemen aşağıda
English → scroll down

🌐 GitHub Pages — Tarayıcıda Çalışan Canlı Demo

Uygulamanın hafif sürümü GitHub Pages’te yayınlanır ve tamamen tarayıcıda çalışır. Hiçbir kurulum, Docker, sunucu veya model eğitimi gerektirmez.

👉 https://muhmteminylmz.github.io/phishing-detector/

✅ ML modeli önceden eğitilmiş, JSON olarak tarayıcıya gömülmüştür
✅ URL tarama tamamen istemci tarafında çalışır (sunucuya veri gönderilmez)
✅ Tarama geçmişi ve istatistikler localStorage’da tutulur
✅ main branch’e her push’ta GitHub Actions ile otomatik güncellenir

Not: GitHub Pages sürümü yalnızca URL’nin yapısal özelliklerini analiz eder. SSL sertifikası, WHOIS ve HTML analizi gibi sunucu taraflı özellikler yalnızca Docker ile tam sürümde kullanılabilir.

🇹🇷 Türkçe — Tek Tuşla Çalıştır (Docker)

Tek Gereksinim: Docker

Docker’ı kur, başlat, işte bu kadar. Başka hiçbir şeye gerek yok. Python da, Node.js da, veritabanı da — hepsi Docker tarafından otomatik indirilir.

İşletim Sistemi	Docker İndirme Linki
Windows	https://docs.docker.com/desktop/install/windows-install/
Mac	https://docs.docker.com/desktop/install/mac-install/
Linux	`curl -fsSL https://get.docker.com \\| sh`

Docker Desktop’ı kurduktan sonra uygulamayı başlat (sağ alttaki Docker simgesi yeşil olmalı).

Çalıştırma Adımları

Adım 1 — Projeyi indir:

git clone https://github.com/muhmteminylmz/phishing-detector
cd phishing-detector

Adım 2 — Tek komutla başlat:

Windows (CMD — en kolay yol, çift tıkla veya CMD’ye yaz):

start.bat

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File start.ps1

Mac / Linux:

bash start.sh

💡 Detaylı adım adım rehber için: KURULUM.md

Bu kadar. Script her şeyi kendi kendine yapar:

Gerekli tüm kütüphaneleri indirir (ilk seferinde Docker image build edilir ve model eğitilir ~3-7 dk)
Veritabanını ve cache’i başlatır
ML modeli zaten hazır gelir — image içinde önceden eğitilmiştir, her seferinde yeniden eğitilmez
Backend ve frontend’i başlatır
Uygulama hazır olana kadar bekler
Tarayıcıyı otomatik açar

Ne Göreceksin?

Script başarıyla tamamlandığında terminalde şunu göreceksin:

✅  Phishing Detector başarıyla çalışıyor!
══════════════════════════════════════════
🌐  Dashboard (Ana Sayfa) :  http://localhost
📡  API Dokümantasyonu    :  http://localhost:8000/docs
📊  Grafana İzleme        :  http://localhost:3001
🔭  Prometheus            :  http://localhost:9090

Ve tarayıcın http://localhost adresinde otomatik açılacak:

URL kutusuna bir adres yaz (örn. http://paypal-secure-login.xyz) ve “Tara” butonuna bas
Sonuç: Phishing mi? Güvenli mi? Risk skoru nedir?

Model Eğitimi — Otomatik ve Tek Seferlik

ML modeli Docker image build sırasında otomatik eğitilir ve image’ın içine gömülür. Bu sayede:

✅ bash start.sh her çalıştırıldığında model zaten hazırdır — yeniden eğitim yapılmaz
✅ docker compose down yapıp tekrar up yaptığında model volume’da saklanır
✅ docker compose down -v ile volume’lar silinse bile model image’dan otomatik kopyalanır
✅ Sadece docker compose build veya make build yapıldığında model yeniden eğitilir

İlk docker compose up komutu image’ları build ederken model eğitimini de yapar (toplam ~3-7 dk). Sonraki her çalıştırmada container saniyeler içinde hazır olur.

💡 Modeli manuel olarak yeniden eğitmek istersen: make train komutu ile çalışan container içinde eğitimi tekrarlayabilirsin.

Arka planda çalışan Vmmem nedir? Windows’ta Docker çalışırken Vmmem adlı bir süreç görürsün. Bu, Docker Desktop’ın kullandığı WSL2 sanal makinesidir ve yalnızca Windows’a özgüdür (Mac/Linux’ta görünmez).

💡 Vmmem bellek kullanımını sınırlamak için: %USERPROFILE%\.wslconfig dosyası oluşturup şunu ekle:
[wsl2]
memory=4GB
processors=2
Sonra PowerShell’de wsl --shutdown çalıştır ve Docker Desktop’ı yeniden başlat.

PC Kapanırsa veya Servisler Durursa Ne Olur?

Model Docker image’ının içinde önceden eğitilmiş olarak saklanır. Bu nedenle:

PC kapanırsa: Docker Desktop’ı başlat ve bash start.sh çalıştır — model zaten hazır, yeniden eğitim yok
docker compose down yapılırsa: Model Docker volume’unda saklanır, docker compose up -d ile anında başlar
docker compose down -v ile volume silinirse: Model image’dan volume’a otomatik kopyalanır, yine yeniden eğitim yok

💡 Checkpoint/resume sistemi hâlâ mevcuttur — make train ile modeli manuel eğitirken PC kapanırsa kaldığı yerden devam eder.

Uzak Bilgisayarda (Remote) Eğitim

Projeyi uzak bir sunucuda (VPS, bulut VM, üniversite sunucusu vb.) eğitmek için:

# 1. Uzak sunucuya bağlan
ssh kullanici@sunucu-adresi

# 2. Projeyi indir
git clone https://github.com/muhmteminylmz/phishing-detector
cd phishing-detector

# 3. Docker kur (Linux sunucularda)
curl -fsSL https://get.docker.com | sh

# 4. Başlat
bash start.sh

İpucu: SSH bağlantısı kesilse bile eğitimin devam etmesi için screen veya tmux kullan:
tmux new -s training
bash start.sh
# Ctrl+B, D ile çık — eğitim arka planda devam eder
# Tekrar bağlanmak için: tmux attach -t training

Sık Kullanılan Komutlar

# Servisleri durdur
docker compose down

# Logları izle (Ctrl+C ile çık)
docker compose logs -f

# Tekrar başlat
bash start.sh

# Yardım
make help

Sorun Giderme

WSL hatası: execvpe(/bin/bash) failed: No such file or directory: → Bu hata Windows’ta WSL (Linux Alt Sistemi) kurulu olmadığında oluşur. Çözüm: PowerShell ile başlat (WSL gerektirmez):

powershell -ExecutionPolicy Bypass -File start.ps1

Veya WSL’i kurmak istersen PowerShell’i yönetici olarak açıp şunu çalıştır:

wsl --install

Sonra bilgisayarı yeniden başlat ve bash start.sh komutunu tekrar dene.

“Docker bulunamadı” hatası: → Docker Desktop’ı yükle ve başlat, sonra tekrar başlat.

“Docker çalışmıyor” hatası: → Docker Desktop uygulamasını aç (sağ alttaki sistem saatinde Docker simgesi görünmeli).

Port zaten kullanımda (port already in use):

docker compose down
bash start.sh

Servisler yavaş başlıyor: → İlk çalıştırmada Docker image’ları indirildiği için 5-10 dakika sürebilir. Bir sonraki seferinde çok daha hızlı olacak.

Logları görmek istiyorum:

docker compose logs -f          # tüm servisler
docker compose logs -f backend  # sadece backend

🇬🇧 English — One-Command Start

Try it now — no install needed

A lightweight version of the app runs entirely in your browser on GitHub Pages:

👉 https://muhmteminylmz.github.io/phishing-detector/

The GitHub Pages version uses a pre-trained ML model exported to JSON. URL scanning runs 100% client-side — no data is sent to any server. Scan history and stats are stored in localStorage.

Full version with Docker

Get Docker Desktop — no Python, Node.js, or database setup needed. Everything is downloaded automatically.

Run

Windows (CMD — easiest, double-click or type in CMD):

git clone https://github.com/muhmteminylmz/phishing-detector
cd phishing-detector
start.bat

Windows (PowerShell — no WSL required):

git clone https://github.com/muhmteminylmz/phishing-detector
cd phishing-detector
powershell -ExecutionPolicy Bypass -File start.ps1

Mac / Linux:

git clone https://github.com/muhmteminylmz/phishing-detector
cd phishing-detector
bash start.sh

That’s it. The script:

Downloads all dependencies automatically (Docker images)
ML model is pre-trained during image build (~3-7 min first time, instant on subsequent runs)
Starts the database, cache, backend, and frontend
Waits until the app is actually ready
Opens the browser automatically at http://localhost

What you’ll see

The dashboard at http://localhost lets you type any URL and scan it for phishing. The API docs at http://localhost:8000/docs let you test the API interactively.

Commands

docker compose down          # stop all services
docker compose logs -f       # watch live logs
bash start.sh                # start / restart everything
make help                    # list all make targets

✨ Features

Ensemble ML Model — XGBoost + LightGBM + Random Forest with soft voting
47 URL Features — URL structure, SSL, WHOIS, HTML analysis, blacklist
Real-time API — FastAPI with async I/O, Redis caching, rate limiting
Modern Dashboard — React + TypeScript + TailwindCSS
Bulk Scanning — Upload CSV or paste URLs, export results
Monitoring — Prometheus metrics + Grafana dashboards

🏗️ Architecture

┌─────────────┐    ┌──────────────────────────────────────────┐
│   Browser   │───▶│              Nginx (port 80)              │
└─────────────┘    └──────┬───────────────────┬───────────────┘
                          │                   │
                   ┌──────▼──────┐    ┌───────▼──────┐
                   │  Frontend   │    │   Backend     │
                   │ React/Vite  │    │  FastAPI      │
                   │ (port 3000) │    │  (port 8000)  │
                   └─────────────┘    └──────┬────────┘
                                             │
                          ┌──────────────────┼──────────────┐
                          │                  │              │
                   ┌──────▼──────┐  ┌────────▼────┐  ┌─────▼──────┐
                   │ PostgreSQL  │  │    Redis     │  │ ML Models  │
                   │ (port 5432) │  │ (port 6379)  │  │  (joblib)  │
                   └─────────────┘  └─────────────┘  └────────────┘

📡 API Reference

Method	Path	Description
`POST`	`/api/v1/scan/url`	Scan a single URL
`POST`	`/api/v1/scan/bulk`	Bulk scan (up to 100 URLs)
`GET`	`/api/v1/scan/history`	Paginated scan history
`GET`	`/api/v1/reports/stats`	Aggregate statistics
`GET`	`/api/v1/health`	Health check

curl -X POST http://localhost:8000/api/v1/scan/url \
  -H "Content-Type: application/json" \
  -d '{"url": "http://paypa1-secure.xyz/login"}'

{
  "is_phishing": true,
  "confidence": 0.94,
  "risk_score": 94,
  "risk_level": "CRITICAL"
}

🧪 Tests

make test

🤝 Contributing

Fork the repository
Create a feature branch
Run make test
Submit a pull request

📄 License

MIT License