kemal-waf Documentation

Web Application Firewall built with Kemal framework

View the Project on GitHub kursadaltan/kemalwaf

GeoIP Filtering - MaxMind MMDB Entegrasyonu

WAF, MaxMind MMDB dosyası ile ülke bazlı erişim kontrolü sağlar.

Özellikler

Konfigürasyon

Environment Variables

# GeoIP'i etkinleştir
export GEOIP_ENABLED=true

# MMDB dosyası yolu (ÖNERİLEN - en hızlı, rate limit yok)
export GEOIP_MMDB_FILE=/path/to/GeoLite2-Country.mmdb

# Engellenecek ülkeler (ISO 3166-1 alpha-2 kodları, virgülle ayrılmış)
export GEOIP_BLOCKED_COUNTRIES=CN,RU,KP

# İzin verilecek ülkeler (whitelist - sadece bu ülkelerden erişim)
export GEOIP_ALLOWED_COUNTRIES=US,GB,DE,FR

MMDB Dosyası Kurulumu

  1. MMDB dosyasını indirin:
    • MaxMind GeoLite2: https://dev.maxmind.com/geoip/geoip2/geolite2/
    • Veya internetten ücretsiz MMDB dosyaları bulabilirsiniz
  2. mmdblookup aracını yükleyin: 
    # macOS
brew install libmaxminddb
   
# Ubuntu/Debian
sudo apt-get install mmdb-bin
   
# veya MaxMind'in resmi installer'ını kullanın
# https://github.com/maxmind/libmaxminddb
  3. MMDB dosyasını projeye kopyalayın: 
    mkdir -p data
cp /path/to/GeoLite2-Country.mmdb data/
  4. Environment variable’ı ayarlayın: 
    export GEOIP_MMDB_FILE=data/GeoLite2-Country.mmdb

Kullanım Örnekleri

1. MMDB Dosyası ile Kullanım (ÖNERİLEN)

# MMDB dosyasını indirip ayarla
export GEOIP_ENABLED=true
export GEOIP_MMDB_FILE=data/GeoLite2-Country.mmdb
export GEOIP_BLOCKED_COUNTRIES=CN,RU,KP

./bin/kemal-waf

Avantajları:

2. Belirli Ülkeleri Engelleme (MMDB ile)

export GEOIP_ENABLED=true
export GEOIP_MMDB_FILE=data/GeoLite2-Country.mmdb
export GEOIP_BLOCKED_COUNTRIES=CN,RU,KP

./bin/kemal-waf

Bu ayarla, Çin, Rusya ve Kuzey Kore’den gelen istekler engellenir.

3. Sadece Belirli Ülkelerden İzin Verme (Whitelist)

export GEOIP_ENABLED=true
export GEOIP_MMDB_FILE=data/GeoLite2-Country.mmdb
export GEOIP_ALLOWED_COUNTRIES=US,GB,DE,FR

./bin/kemal-waf

Bu ayarla, sadece ABD, İngiltere, Almanya ve Fransa’dan gelen istekler kabul edilir.

Öncelik Sırası

  1. IP Whitelist (en yüksek öncelik)
  2. IP Blacklist
  3. GeoIP Allowed Countries (whitelist)
  4. GeoIP Blocked Countries (blacklist)
  5. Rate Limiting
  6. WAF Rules

Cache

GeoIP lookup sonuçları 1 saat süreyle cache’lenir. Bu sayede:

Cache otomatik olarak temizlenir (1 saatte bir).

MMDB Dosyası

Özellikler

MMDB Dosyası İndirme

Ülke Kodları

ISO 3166-1 alpha-2 formatında ülke kodları kullanılır:

Tüm ülke kodları: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Logging

GeoIP engellemeleri structured log ve audit log’a yazılır:

{
  "timestamp": "2025-11-11T12:00:00Z",
  "event_type": "waf_request",
  "client_ip": "1.2.3.4",
  "blocked": true,
  "rule_message": "GeoIP blocked: Country CN (China) is blocked",
  "source": "geoip"
}

Performans

MMDB dosyası kullanımı çok hızlıdır! Cache ile birlikte kullanıldığında performans daha da artar.

Notlar