Gerçek Zamanlı Fraud Skorlama Sistemi

Kart işlemlerini gerçek zamanlı olarak akış üzerinden skorlayan bir fraud tespit sistemi. Her işlem bir akışa (Redis Streams tx.raw) yazılır; durum bilgili bir skorlama tüketicisi (consumer group) kartın davranış profilini okuyarak bir dizi fraud sinyalini değerlendirir, 0–100 risk skoru ve ONAY / İNCELEME / RED kararı üretir. Dashboard bu kararı, her işlemin neden o skoru aldığını gösteren açıklanabilir sinyal dökümüyle canlı sunar.

Öğrenme/portföy projesidir. Yalnızca test PAN'ları kullanılır, gerçek kart verisi yoktur; kart numaraları panelde maskelenir.

---

Neden akış (streaming) mimarisi?

Fraud tespiti düşük gecikme ister: kart okutulduğu anda karar verilmeli. Bu yüzden istek/yanıt yerine olay akışı kurdum — işlemler bir akışa düşer, skorlama tüketicileri bunları consumer group ile paralel işler. Taşıma katmanı Redis Streams; ancak mimari Kafka'ya birebir taşınır (stream → topic, consumer group → consumer group), böylece ev/lab ölçeğinde hafif kalır, üretimde Kafka'ya geçer.

---

Mimari

flowchart LR
    UI["Dashboard · nginx"] -->|POST /api/simulate| API["API / Üretici · FastAPI"]
    API -->|XADD| S1[("Redis Stream<br/>tx.raw")]
    S1 -->|consumer group| SC["Scorer<br/>durum bilgili skorlama"]
    SC -->|XADD| S2[("Redis Stream<br/>tx.scored")]
    SC <-->|profil · velocity| ST[("Redis<br/>kart durumu")]
    SC -.->|ui:events pub/sub| API
    API -.->|WebSocket| UI

    classDef stream fill:#0B2E52,stroke:#0B2E52,color:#fff;
    class S1,S2,ST stream;

Loading

Servis	Rol	Teknoloji	Host portu
frontend	Kurumsal dashboard (gauge + sinyal dökümü)	nginx	tek açılan port
api	Üretici + WebSocket köprüsü + istatistik	FastAPI + asyncio	(iç)
scorer	Durum bilgili skorlama tüketicisi	asyncio + Redis Streams	(iç)
redis	Akış + kart profili + pub/sub	Redis 7.2	(iç)

Port çakışması yok: yalnızca dashboard bir host portu açar (FRONTEND_PORT, varsayılan 8090). redis / api / scorer tamamen iç ağdadır. Çakışma olursa tek satır .env değişikliğiyle çözülür.

---

Fraud sinyalleri (skorlama)

Skor 0–100 arası birikir; bantlar: <30 ONAY · 30–64 İNCELEME · ≥65 RED. Tek bir güçlü sinyal genelde incele (hold) getirir; red için kara liste ya da sinyallerin birleşmesi gerekir — gerçek fraud operasyonlarındaki gibi.

Sinyal	Ne yakalar	Katkı
Hız (velocity)	Kısa sürede çok sayıda işlem	+30…55
İmkânsız seyahat	İki işlem arası zorunlu hız > 900 km/s	+40
Tutar anomalisi	Kartın geçmiş ortalamasına göre σ sapması	+25…40
Riskli kategori (MCC)	Kripto / kumar / para transferi	+20
Gece + yüksek tutar	01–06 arası yüksek tutar	+12
Kart sahibi olmayan (CNP)	İnternet işlemi + yüksek tutar	+12
Yeni cihaz	Kart için bilinmeyen cihaz	+15
Kara liste	Bilinen sahte kart	+100 (anında RED)

Durum bilgili sinyaller (velocity, imkânsız seyahat, tutar anomalisi) kartın Redis'teki davranış profilinden hesaplanır ve her işlemde güncellenir.

---

Senaryolar

Dashboard'dan seçin ya da "Rastgele" bırakın:

Senaryo	Beklenen
Normal Alışveriş	ONAY (düşük skor)
Hız Saldırısı (Velocity)	İNCELEME
İmkânsız Seyahat (İstanbul→New York, 2 dk)	RED
Tutar Anomalisi (ort. 250₺ → 48.000₺)	İNCELEME
Riskli Kategori · Gece (kripto, 03:30)	RED
Yeni Cihaz · CNP	İNCELEME
Kara Liste Kartı	RED

"Sıfırla" butonu kart profillerini ve sayaçları baştan tohumlar (tekrarlı demo).

---

Çalıştırma

git clone https://github.com/sayha2304/fraud-detection.git
cd fraud-detection
cp .env.example .env

İsteğe bağlı — port boş mu bak (doluysa .env'de FRONTEND_PORT değiştir):

ss -tlnp | grep ":8090 " || echo "8090 boş"

Ardından:

docker compose up -d --build

Dashboard: http://SUNUCU_IP:8090 → senaryo seç → İşlem Gönder. Risk göstergesi, sinyal dökümü ve canlı akış güncellenir. Sağlık: curl http://SUNUCU_IP:8090/api/stats · Durdurma: docker compose down

Skorlamayı ölçeklemek için tüketici sayısını artırabilirsiniz (consumer group otomatik dağıtır):

docker compose up -d --scale scorer=3

---

Skorlama motoru testleri

Skorlama motoru bağımlılıksız ve birim testlidir (her sinyal, bant, coğrafi hesap):

python3 -m unittest scoring.test_scoring -v

---

Proje yapısı

fraud-detection/
├── scoring/            # skorlama motoru (bağımlılıksız, testli)
│   ├── transactions.py # İşlem/CardState modeli, MCC, senaryolar
│   ├── geo.py          # haversine + imkânsız seyahat
│   ├── rules.py        # ağırlıklı kural motoru → skor + neden + karar
│   └── test_scoring.py # birim testler
├── scorer/             # Redis Streams tüketicisi (consumer group)
├── api/                # FastAPI üretici + WebSocket köprüsü
├── frontend/           # kurumsal dashboard (gauge + sinyal dökümü)
├── docker-compose.yml
└── .env.example

---

Güvenlik notu (PCI)

Panelde ve akışta kart numaraları ilk 6 + son 4 olarak maskelenir. Yalnızca standart test PAN'ları kullanılır; gerçek kart verisi işlenmez veya saklanmaz.

---

Lisans

Tüm Hakları Saklıdır. Kod görüntülenebilir ancak izinsiz kullanılamaz, kopyalanamaz veya dağıtılamaz. Ayrıntılar için LICENSE.

---

Sayha Kılıç · ödeme sistemleri & fraud — sayha.cloud