TrustMask AI

Kurumsal ekipler icin tasarlanmis, Turkce odakli, hibrit (kural + yapay zeka) bir veri anonimlestirme motoru.

TrustMask AI; metinlerdeki kisiyi tanimlayici verileri tespit eder, cakisan bulgulari onceliklendirme ile cozer ve guvenli placeholder'lara donusturur. Hem API hem CLI olarak calisabilir.

---

Neden TrustMask AI?

• Hibrit tespit motoru: Regex tabanli net formatlar (TC, IBAN, kart, e-posta vb.) + BERT tabanli NER birlikte calisir.
• Turkce odakli NLP: savasy/bert-base-turkish-ner-cased modeli ile kisi/kurum/lokasyon gibi varliklar baglama duyarli ele alinir.
• Cakisma cozumleme: Ayni metin araligina denk gelen birden fazla bulgu, oncelik ve guven skoruna gore tekilleştirilir.
• Production hazir servis: Flask API, CORS destegi ve Waitress ile coklu thread servisleme.
• Kolay entegrasyon: Python kutuphanesi, REST API ve CLI akislari tek kod tabani uzerinden yonetilir.

---

Mimari Genel Bakis

flowchart LR
    A[Client: Web / Mobile / Bot / CLI] --> B[Flask Routers]
    B --> C[Security Layer\nValidation + CORS + Error Handling]
    C --> D[Hybrid Orchestrator\nKVKKAnonymizer]

    D --> E[Rule Detectors\nTC / Phone / Email / IBAN / Card / Address]
    D --> F[NLP Name Detector]
    D --> G[AI NER Service\nBERT Turkish NER]

    E --> H[Entity Pool]
    F --> H
    G --> H

    H --> I[Confidence Filter]
    I --> J[Overlap Resolver]
    J --> K[Masking Engine\nPlaceholder Replacement]
    K --> L[Sanitized Output + Metadata]

    M[(HF Model Cache)] -. lazy load .-> G
    N[(Optional API Gateway)] -. production .-> C

Loading

Katmanlar

Katman	Sorumluluk	Dosyalar
Presentation	HTTP endpointleri ve CLI girisi	api.py, main.py
Security & Validation	Input dogrulama, CORS, hata sinirlama	api.py
Orchestration	Tum detector'lari calistirma, pipeline yonetimi	anonymizer.py
Detection (Rule-based)	Format tabanli PII tespiti	detectors/
Detection (NLP/AI)	Baglam tabanli isim/varlik tespiti	nlp/name_detector.py, nlp/ai_ner.py
Domain Model	Entity ve sonuc veri modelleri	entities.py, config.py
Runtime	Production server ve deploy routing	run_production.py, vercel.json

Cekirdek Bilesenler

• anonymizer.py
  • KVKKAnonymizer sinifi tum detector'lari orkestre eder.
  • anonymize(text, min_confidence) ile sonuc nesnesi uretir.
  • _resolve_overlaps() ile cakisan varliklari cozer.
  • _apply_anonymization() ile yer degistirme (masking) uygular.
• detectors/
  • Kural tabanli detector katmani.
  • Her detector BaseDetector soylesmesine uygun calisir.
• nlp/
  • NameDetector: sozluk + baglam + unvan tabanli isim tespiti.
  • AINERDetector: BERT pipeline ile NER, lazy-load yaklasimi.
• api.py
  • REST endpointleri: /anonymize, /anonymize/batch, /stats, /health, /info.
• main.py
  • Tek metin, dosya, stdin ve interaktif CLI kullanimini yonetir.
• run_production.py
  • Waitress ile production servis baslatir (0.0.0.0:5000, threads=8).

---

Tespit Edilen Veri Kategorileri

Asagidaki veri siniflari sistemde dogrudan desteklenir (detector + config katmani):

• Kimlik: TC kimlik, musteri/abone/sozlesme/cagri kayit id bilgileri
• Iletisim: Cep telefonu, sabit hat, e-posta
• Finans: IBAN, kredi karti, banka bilgileri/banka adi
• Kisi: Ad, soyad, tam ad, ebeveyn adi
• Konum: Adres, il/ilce
• Belge/kurumsal kimlik: Pasaport, yabanci kimlik, VKN, SGK sicil, MERSIS, ehliyet, musteri/abonelik/sozlesme/police/dosya id bilgileri
• Dijital tanimlayicilar: IP, MAC, IMEI/cihaz kimligi, sosyal medya profili, kullanici adi, sifre, PIN/PUK/OTP, token/API anahtari
• Ozel nitelikli veri baglamlari: Saglik, biyometrik, genetik, din/mezhep/inanc, siyasi/felsefi gorus, sendika/dernek/vakif uyeligi, adli veri, etnik koken, cinsel hayat
• Diger: Dogum tarihi/yili, plaka, cinsiyet gibi hassas alanlar

Maskelenen ciktilar placeholder formatinda doner (or. [TC_ID], [PHONE], [EMAIL], [ADDRESS]). API yanitlari entity metadata'sini ham degeri dondurmeden verir; bu sayede arayuz sayim/raporlama yapabilir ama hassas deger tekrar ifsa edilmez.

Kapsam notu: KVKK Kurumu'nun tanimina gore kisisel veri, kimligi belirli veya belirlenebilir gercek kisiye iliskin her turlu bilgidir. Ozel nitelikli kisisel veriler ise Kanun'da sinirli sayma yoluyla belirlenen kategorilerdir; bu proje o listeyi ayri detector katmani olarak ele alir. Kaynaklar: Kisisel Veriler, Ozel Nitelikli Kisisel Veriler.

---

Proje Dizini

TrustMask-main/
├── anonymizer.py
├── api.py
├── main.py
├── run_production.py
├── config.py
├── entities.py
├── requirements.txt
├── vercel.json
├── detectors/
│   ├── base_detector.py
│   ├── tc_kimlik_detector.py
│   ├── phone_detector.py
│   ├── email_detector.py
│   ├── iban_detector.py
│   ├── credit_card_detector.py
│   ├── address_detector.py
│   ├── date_detector.py
│   ├── ip_detector.py
│   ├── plate_detector.py
│   ├── customer_id_detector.py
│   ├── partial_data_detector.py
│   ├── kvkk_extended_detector.py
│   └── extra_detectors.py
└── nlp/
    ├── name_detector.py
    └── ai_ner.py

---

Kurulum

1) Ortam Hazirlama

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

2) Production Sunucuyu Baslatma

python run_production.py

Varsayilan servis adresi: http://localhost:5000

3) Gelistirme Modu API

python api.py --host 0.0.0.0 --port 5000 --debug

Test

python3 -m pytest -q

Operasyonel Ortam Degiskenleri

Degisken	Varsayilan	Aciklama
TRUSTMASK_ENABLE_AI_NER	true	Transformer tabanli NER katmanini acar/kapatir.
TRUSTMASK_NER_MODEL	savasy/bert-base-turkish-ner-cased	Hugging Face NER model adi.
TRUSTMASK_MAX_TEXT_LENGTH	200000	Tek istekte kabul edilen maksimum karakter sayisi.
TRUSTMASK_MAX_BATCH_SIZE	50	Batch endpoint maksimum metin sayisi.
TRUSTMASK_CORS_ORIGINS	*	Virgulle ayrilmis izinli origin listesi.
TRUSTMASK_HOST / TRUSTMASK_PORT / TRUSTMASK_THREADS	0.0.0.0 / 5000 / 8	run_production.py servis ayarlari.

---

API Dokumantasyonu

Base URL (lokal): http://localhost:5000

Method	Endpoint	Aciklama
GET	/health	Servis saglik kontrolu
GET	/info	API kabiliyetleri ve desteklenen alanlar
POST	/anonymize	Tek metin anonimlestirme
POST	/anonymize/batch	Toplu metin anonimlestirme
POST	/stats	Tespit istatistikleri

POST /anonymize ornek

curl -X POST http://localhost:5000/anonymize ^
  -H "Content-Type: application/json" ^
  -d "{\"text\":\"Musteri no: VOD-123456789, telefon: 0532 111 22 33\",\"min_confidence\":0.5}"

Ornek donus:

{
  "is_personal_data_detected": true,
  "detected_data_types": [
    "CUSTOMER_ID",
    "MOBILE_PHONE"
  ],
  "sanitized_text": "Musteri no: [MUSTERI_NO], telefon: [CEP_TELEFONU]",
  "entities": [
    {
      "entity_type": "CUSTOMER_ID",
      "start_pos": 0,
      "end_pos": 25,
      "confidence": 0.98,
      "placeholder": "[MUSTERI_NO]",
      "context": null
    }
  ],
  "detection_errors": []
}

---

CLI Kullanimi

Tek metin

python main.py --text "Merhaba, ben Ahmet Yilmaz. Telefonum 0532 000 00 00"

Dosya isleme

python main.py --file input.txt --output output.txt

Interaktif mod

python main.py --interactive

Stdin

echo "TC: 12345678901" | python main.py --stdin

Isim tespitini kapatma

python main.py --text "Ayse Yilmaz" --no-names

---

Deployment Notlari

• Waitress WSGI: run_production.py uzerinden production servisleme.
• Vercel Destegi: vercel.json ile api.py serverless, index.html static route olarak yayinlanabilir.
• Model yukleme: BERT modeli ilk ihtiyacta yuklenir (lazy loading), ilk istekte ekstra gecikme olabilir.

---

Guvenlik ve Operasyonel Notlar

• Bu surumde API seviyesinde kimlik dogrulama (JWT/API key) bulunmaz; production'da gateway veya reverse-proxy ile koruma onerilir.
• Hata yonetiminde 500 yanitlari error mesaji dondurur; kurumsal ortamlarda merkezi loglama + sanitize edilmis hata formati onerilir.
• Model bagimliligi nedeniyle soguk baslangicta internet/model cache gereksinimleri planlanmalidir.

---

Gelistirme Yol Haritasi (Onerilen)

• Otomatik test kapsami (pytest) arttirimi
• Role-based API access / token tabanli erisim kontrolu
• Dockerfile + healthcheck + observability (metrics/log tracing)
• Daha ayrintili benchmark raporlari

---

Lisans

Bu proje MIT lisansi ile lisanslanmistir.