TokenTrace

Pasif İstemci Tarafı Maruziyet Analizi
Frontend görünürlüğünü etik sınırlar içinde okunabilir güvenlik istihbaratına dönüştürür.

TokenTrace, bir hedef web sayfasının istemci tarafında görünür HTML kaynağını ve yalnızca o sayfanın doğrudan referans verdiği JavaScript dosyalarını pasif olarak inceleyen etik bir maruziyet analiz platformudur.

Amaç, istemci tarafında istemeden görünür hale gelmiş güvenlik sinyallerini savunmacı ekipler için daha okunabilir, daha açıklanabilir ve daha yönetilebilir hale getirmektir.

İçindekiler

1. Ürün ve Amaç

• Proje Tanımı
• Tasarım Hedefi
• Öne Çıkan Özellikler

2. Arayüz ve Operasyon Modeli

• Widget Mimarisi
• Budget ve Scope Modeli
• Budget Matrisi

3. Teknik Mimari

• Sistem Mimarisi
• Analiz Akışı
• Diyagramlar
• Ekran Çizimleri

4. Kurulum ve Kullanım

• Kurulum
• Kullanım
• API Uçları
• Örnek İstek ve Çıktı

5. Analiz Mantığı

• Bulgular ve Skorlama
• Etik Kullanım Bildirimi
• Sınırlamalar
• False Positive Notu

6. Doğrulama ve Gelecek

• Test Senaryoları
• v2 Yol Haritası
• Son Not

Proje Tanımı

TokenTrace bir saldırı aracı değildir.

Yapmaz:

• aktif sömürü testi
• brute force
• yetki atlatma
• recursive crawl
• gizli yol fuzzing
• payload enjeksiyonu
• saldırı zinciri kurma

Buna karşılık şu problemi çözer:

• frontend derlemelerine yanlışlıkla gömülmüş secret göstergeleri
• token veya auth kalıntıları
• riskli client-side storage kullanımı
• staging, dev veya internal ortam referansları
• istemciye sızmış cloud yapılandırmaları
• hassas endpoint referansları
• test artefact ve geliştirici hataları

Tasarım Hedefi

TokenTrace, “tek dosyalık güvenlik scripti” gibi değil, gerçek bir güvenlik ürünü gibi hissedilmek üzere tasarlanmıştır.

Hedefler:

• pasif ve etik kapsam
• profesyonel ve modern dashboard deneyimi
• Türkçe raporlama dili
• bağlamsal ve dengeli severity yaklaşımı
• false positive farkındalığı
• üretim tarzı kod organizasyonu
• kolay genişletilebilir servis mimarisi

Öne Çıkan Özellikler

• FastAPI tabanlı Python backend
• modern koyu temalı güvenlik dashboard arayüzü
• sıkı scope ve budget kontrolleri
• HTML + doğrudan bağlı JS analizi
• secret, token, auth misuse, cloud config, endpoint ve environment leak tespiti
• opsiyonel yüksek entropy modülü
• severity + confidence score üretimi
• Türkçe açıklama, aksiyon ve false positive notları
• JSON export
• filtrelenebilir bulgu tablosu
• detay modalı, canlı telemetri ve risk özeti paneli

Widget Mimarisi

Arayüz, tek sayfalık bir dashboard içinde birden fazla işlevsel widget mantığıyla tasarlanmıştır. Böylece kullanıcı aynı ekran içinde hem komut verebilir hem ilerlemeyi izleyebilir hem de sonuçları inceleyebilir.

Ana widget’lar

1. Hero Widget Ürünün konumlandırmasını, etik çerçevesini ve giriş aksiyonunu sunar.

2. Scope Guard Widget Pasif analiz karakterini, kapsam sınırlarını ve çekirdek ürün kimliğini gösterir.

3. Analysis Command Widget Kullanıcının hedef URL, timeout, dosya limiti, scope modu ve analiz seçeneklerini belirlediği kontrol yüzeyidir.

4. Preset Widget Varsayılan analiz davranışını ve false positive azaltma yaklaşımını hızlıca açıklar.

5. Live Telemetry Widget Analiz ilerleme durumu, sayaçlar, log akışı ve işlem adımlarını gösterir.

6. Progress Widget Adım bazlı ilerleme yüzdesini ve operasyon aşamasını sunar.

7. Summary Widget Bulgu yoğunluğunu seviye bazında özetler.

8. Insight Widget En baskın risk tonunu kısa bir özet olarak verir.

9. Findings Table Widget Sonuçların filtrelenebilir, sıralanabilir ve detay açılabilir biçimde incelenmesini sağlar.

10. Findings Posture Widget Genel bulgu yoğunluğunu “acil müdahale”, “düşük yoğunluklu sinyal” gibi anlaşılır dile çevirir.

11. Export Widget JSON, metin özet ve kopyalanabilir rapor çıktıları üretir.

12. About / Ethics Widget Ürünün sınırlarını, kullanım amacını ve etik çerçevesini açıklar.

Eklenebilir ileri widget fikirleri

• Budget Heatmap Widget Timeout, JS sayısı ve dosya boyutu bütçelerinin doluluk oranını görselleştirebilir.

• Category Distribution Widget Kategori bazlı bulgu dağılımı için mini chart gösterebilir.

• Source Footprint Widget Hangi JS dosyalarının en çok bulgu ürettiğini sıralayabilir.

• Diff Widget Eski ve yeni analiz sonuçlarını karşılaştırabilir.

• Team Notes Widget Güvenlik ve frontend ekiplerinin yorum bırakmasını sağlayabilir.

Budget ve Scope Modeli

TokenTrace’in en önemli prensiplerinden biri sınırlı çalışma bütçesidir. Buradaki budget, hem performans hem etik sınır anlamına gelir.

Temel budget bileşenleri

• timeout Tek bir isteğin ne kadar süreceğini sınırlar.

• max_js_files Analiz edilecek doğrudan JS dosyası sayısını sınırlar.

• max_js_size_kb Her JS dosyasının maksimum boyutunu sınırlar.

• scope_mode Yalnızca aynı-origin veya güvenli referans kümesinde çalışmayı zorunlu kılar.

• direct_js_only Sadece HTML içinde doğrudan referans verilen script’leri işler.

• enable_entropy Daha pahalı ve daha gürültülü olabilecek entropy taramasını açıp kapatır.

• export_json Sonucun dosyaya alınması davranışını kontrol eder.

Neden budget önemli?

• etik sınırların dışına çıkmamak için
• performansı öngörülebilir tutmak için
• kullanıcıya kontrollü analiz davranışı sunmak için
• istemeden genişleyen tarama yüzeyini önlemek için
• kaynak tüketimini açıklanabilir tutmak için

Budget ilkeleri

• URL dışı alan genişlemesi yok
• recursive crawl yok
• brute force yok
• saldırı zinciri yok
• yalnızca hedef HTML + doğrudan JS

Budget Matrisi

Budget Alanı	Varsayılan	Üst Sınır	Güvenlik Etkisi	Performans Etkisi	Not
timeout	12 sn	30 sn	Aşırı bekleme ve kontrolsüz akışı önler	Yavaş hedeflerde analiz süresini belirler	Düşük timeout bazı hedeflerde eksik veri üretebilir
max_js_files	10	25	Kapsam büyümesini sınırlar	Daha çok dosya = daha fazla işlem süresi	Yalnızca doğrudan referanslı script’ler sayılır
max_js_size_kb	512 KB	2048 KB	Dev bundle’ların kontrolsüz etkisini sınırlar	Büyük bundle’lar CPU ve parse maliyeti oluşturur	Minified dosyalarda false positive artabilir
scope_mode	same-origin	safe-reference	Etik sınırı belirler	Daha gevşek mod daha fazla network erişimi doğurur	Güvenli referans modu yalnızca belirli host kalıplarını kapsar
direct_js_only	true	true	Zincirleme keşfi tamamen kapatır	Analizi hafif tutar	Bu bir güvenlik freni olarak düşünülmelidir
enable_entropy	true	true/false	Şüpheli rastgele dizeleri bulur	Ek hesaplama maliyeti getirir	Gürültü üretme riski en yüksek alanlardan biridir
export_json	false	true/false	Sonucu arşivlenebilir hale getirir	I/O etkisi düşüktür	CI ve rapor akışları için yararlıdır

Önerilen budget profilleri

1. Güvenli Varsayılan

• timeout: 12
• max_js_files: 10
• max_js_size_kb: 512
• scope_mode: same-origin
• enable_entropy: true

Kullanım: çoğu genel frontend gözden geçirmesi

2. Sıkı Denetim

• timeout: 8
• max_js_files: 6
• max_js_size_kb: 256
• scope_mode: same-origin
• enable_entropy: false

Kullanım: hızlı, düşük gürültülü pre-check

3. Geniş Pasif Görünürlük

• timeout: 20
• max_js_files: 20
• max_js_size_kb: 1024
• scope_mode: safe-reference
• enable_entropy: true

Kullanım: kurumsal frontend dağıtımı veya ağır SPA gözden geçirmesi

Sistem Mimarisi

tokentrace/
├── app/
│   ├── core/
│   │   ├── config.py
│   │   ├── logging_config.py
│   │   ├── patterns.py
│   │   └── safety.py
│   ├── models/
│   │   ├── analysis_request.py
│   │   ├── analysis_result.py
│   │   ├── finding.py
│   │   └── scan_log.py
│   ├── routes/
│   │   ├── api.py
│   │   └── web.py
│   ├── services/
│   │   ├── analysis_service.py
│   │   ├── export_service.py
│   │   ├── extract_service.py
│   │   ├── fetch_service.py
│   │   ├── report_service.py
│   │   └── scoring_service.py
│   ├── static/
│   │   ├── css/
│   │   └── js/
│   ├── templates/
│   └── utils/
├── reports/
├── requirements.txt
├── README.md
└── run.py

Analiz Akışı

1. URL doğrulanır
2. HTML pasif olarak çekilir
3. Script etiketleri ayrıştırılır
4. JS URL’leri normalize edilir
5. Scope kuralları uygulanır
6. Dosya sayısı ve boyut budget’ı uygulanır
7. HTML analiz edilir
8. Her JS dosyası ayrı analiz edilir
9. Bulgular deduplicate edilir
10. Severity ve confidence hesaplanır
11. Türkçe açıklamalar oluşturulur
12. Sonuç arayüz ve export katmanına döndürülür

Diyagramlar

Renk lejantı

• Mavi -> arayüz ve kullanıcı akışı
• Turkuaz -> servisler ve analiz motoru
• Turuncu -> scope / budget karar noktaları
• Kırmızı -> warning / skip / risk alanları
• Yeşil -> başarılı çıktı ve rapor üretimi
• Mor -> açıklama, export ve yardımcı katmanlar

1. Yüksek seviye sistem diyagramı

flowchart LR
    U[Kullanıcı] --> W[Web Arayüzü]
    W --> A[POST /api/analyze]
    A --> S[Analysis Service]
    S --> F[Fetch Service]
    S --> E[Extract Service]
    S --> C[Scoring Service]
    S --> R[Report Service]
    S --> X[Export Service]
    F --> T[Hedef HTML]
    F --> J[Doğrudan JS Dosyaları]
    S --> O[Analysis Result]
    O --> W
    W --> U

    classDef ui fill:#0f2747,stroke:#62d8ff,color:#ffffff,stroke-width:1.5px;
    classDef service fill:#0b3b3f,stroke:#2dd4bf,color:#ffffff,stroke-width:1.5px;
    classDef source fill:#3a2a0f,stroke:#f59e0b,color:#ffffff,stroke-width:1.5px;
    classDef output fill:#16331f,stroke:#22c55e,color:#ffffff,stroke-width:1.5px;
    classDef helper fill:#31204d,stroke:#a78bfa,color:#ffffff,stroke-width:1.5px;

    class U,W,A ui;
    class S,F,E,C service;
    class T,J source;
    class O output;
    class R,X helper;

Loading

2. Scope ve budget denetimi

flowchart TD
    A[Target URL] --> B[HTML Fetch]
    B --> C[Script Extraction]
    C --> D{Same-Origin veya Safe Reference?}
    D -- Hayır --> E[Atla / Warning]
    D -- Evet --> F{Dosya Sayısı Limiti Aşıldı mı?}
    F -- Evet --> E
    F -- Hayır --> G{Dosya Boyutu Limiti Aşıldı mı?}
    G -- Evet --> E
    G -- Hayır --> H[JS Fetch + Analyze]

    classDef input fill:#0f2747,stroke:#60a5fa,color:#ffffff,stroke-width:1.5px;
    classDef process fill:#0b3b3f,stroke:#2dd4bf,color:#ffffff,stroke-width:1.5px;
    classDef decision fill:#4a2e0f,stroke:#f59e0b,color:#ffffff,stroke-width:1.5px;
    classDef reject fill:#4b1d24,stroke:#ef4444,color:#ffffff,stroke-width:1.5px;

    class A input;
    class B,C,H process;
    class D,F,G decision;
    class E reject;

Loading

3. Bulgu üretim hattı

flowchart LR
    I[Ham İçerik] --> P[Pattern Matching]
    P --> Q[Context Filtering]
    Q --> D[Deduplication]
    D --> S[Severity Scoring]
    S --> T[Turkish Explanation Builder]
    T --> O[Final Findings]

    classDef source fill:#13263c,stroke:#60a5fa,color:#ffffff,stroke-width:1.5px;
    classDef analysis fill:#103636,stroke:#14b8a6,color:#ffffff,stroke-width:1.5px;
    classDef score fill:#4a2e0f,stroke:#f59e0b,color:#ffffff,stroke-width:1.5px;
    classDef result fill:#16331f,stroke:#22c55e,color:#ffffff,stroke-width:1.5px;
    classDef explain fill:#31204d,stroke:#a78bfa,color:#ffffff,stroke-width:1.5px;

    class I source;
    class P,Q,D analysis;
    class S score;
    class T explain;
    class O result;

Loading

4. Widget veri akışı

flowchart TB
    A[Analysis Form Widget] --> B[Telemetry Widget]
    B --> C[Summary Widget]
    B --> D[Insight Widget]
    C --> E[Findings Table Widget]
    E --> F[Finding Detail Modal Widget]
    C --> G[Export Widget]
    D --> G

    classDef form fill:#0f2747,stroke:#60a5fa,color:#ffffff,stroke-width:1.5px;
    classDef live fill:#0b3b3f,stroke:#2dd4bf,color:#ffffff,stroke-width:1.5px;
    classDef summary fill:#4a2e0f,stroke:#f59e0b,color:#ffffff,stroke-width:1.5px;
    classDef detail fill:#4b1d24,stroke:#fb7185,color:#ffffff,stroke-width:1.5px;
    classDef export fill:#16331f,stroke:#22c55e,color:#ffffff,stroke-width:1.5px;

    class A form;
    class B live;
    class C,D summary;
    class E,F detail;
    class G export;

Loading

Ekran Çizimleri

Lejant

• [BLUE] kullanıcı ve arayüz yüzeyi
• [CYAN] analiz ve telemetri
• [AMBER] scope, karar ve özet
• [GREEN] export ve başarılı çıktı
• [RED] detay, risk ve bulgu inceleme

1. Ana dashboard kabataslak yerleşim

┌──────────────────────────────────────────────────────────────────────────────┐
│ [BLUE] TokenTrace                         Ana Sayfa / Analiz / Bulgular     │
├──────────────────────────────────────────────────────────────────────────────┤
│ [BLUE] Hero Widget              │ [CYAN] Scope Guard / Mini Stat Cards      │
│ Pasif Maruziyet Analizi         │                                            │
│ CTA + Etik Not                  │                                            │
├──────────────────────────────────────────────────────────────────────────────┤
│ [AMBER] Analysis Command        │ [CYAN] Live Telemetry                     │
│ URL / Timeout / Scope / Limit   │ Durum / Progress / Log / Sayaçlar         │
├──────────────────────────────────────────────────────────────────────────────┤
│ [AMBER] Summary Widget          │ [GREEN] Export Widget                     │
│ Kritik / Yüksek / Orta / Düşük  │ JSON / Copy / Summary                     │
├──────────────────────────────────────────────────────────────────────────────┤
│ [RED] Findings Table Widget                                               │
│ Search / Filter / Sort / Detail Modal                                     │
├──────────────────────────────────────────────────────────────────────────────┤
│ [BLUE] About / Ethics / Limitations Widget                                │
└──────────────────────────────────────────────────────────────────────────────┘

2. Bulgu detay paneli

┌──────────────────────────────────────────────┐
│ [RED] Bulgu Adı                [Kritik]      │
├──────────────────────────────────────────────┤
│ [AMBER] Tür         Secret Exposure          │
│ [BLUE]  Kaynak      /static/app.js           │
│ [BLUE]  Satır       182                      │
│ [GREEN] Güven       95/100                   │
├──────────────────────────────────────────────┤
│ [RED]   Eşleşen İfade                        │
│ [AMBER] Eşleşen Bağlam                       │
│ [AMBER] Neden Önemli                         │
│ [CYAN]  Teknik Açıklama                      │
│ [BLUE]  False Positive Notu                  │
│ [GREEN] Önerilen Aksiyon                     │
│ [BLUE]  Geliştirici Notu                     │
│ [RED]   Risk Özeti                           │
└──────────────────────────────────────────────┘

3. Budget kontrol çizimi

┌──────────────────────┐
│ [BLUE] Target URL    │
└─────────┬────────────┘
          │
          v
┌──────────────────────┐
│ [CYAN] HTML Fetch    │
└─────────┬────────────┘
          │
          v
┌──────────────────────┐
│ [CYAN] JS Extraction │
└─────────┬────────────┘
          │
          v
┌────────────────────────────────┐
│ [AMBER] Scope + Budget Check   │
│ same-origin?                   │
│ file count ok?                 │
│ file size ok?                  │
└─────────┬──────────────────────┘
          │
          v
┌──────────────────────┐
│ [CYAN] JS Analyze    │
└─────────┬────────────┘
          │
          v
┌──────────────────────┐
│ [GREEN] Report Build │
└──────────────────────┘

Kurulum

Gereksinimler

• Python 3.11+
• modern bir tarayıcı
• ağ erişimi olan yerel çalışma ortamı

Adımlar

1. Sanal ortam oluşturun:

python -m venv .venv

2. Sanal ortamı etkinleştirin:

Windows PowerShell:

.venv\Scripts\Activate.ps1

3. Bağımlılıkları yükleyin:

pip install -r requirements.txt

4. Uygulamayı başlatın:

python run.py

5. Tarayıcıda açın:

http://127.0.0.1:8000

Kullanım

Örnek kullanım akışı

1. Hedef URL girin
2. Timeout belirleyin
3. Maksimum JS sayısını girin
4. Maksimum JS boyutunu belirleyin
5. Scope modunu seçin
6. İsterseniz entropy modunu açın
7. İsterseniz JSON export seçeneğini açın
8. Analizi Başlat düğmesine basın
9. Sonuç kartlarını, canlı logları ve bulgu detaylarını inceleyin

Uygun test hedefleri

• https://example.com
• yetkili olduğunuz staging uygulamaları
• kendi frontend build çıktılarınız
• kurum içi izinli güvenlik doğrulama hedefleri

API Uçları

• GET / Ana dashboard

• GET /about Hakkında sayfası

• GET /api/health Sağlık kontrolü

• POST /api/analyze Analiz başlatır

• POST /api/export/json Sonuç nesnesini indirilebilir JSON cevabı olarak döndürür

Örnek İstek ve Çıktı

POST /api/analyze örnek istek

{
  "url": "https://example.com",
  "timeout": 12,
  "max_js_files": 10,
  "max_js_size_kb": 512,
  "scope_mode": "same-origin",
  "direct_js_only": true,
  "enable_entropy": true,
  "export_json": false
}

Örnek sonuç kaynağı

Tam örnek sonuç için:

• reports/example_result.json

Bulgular ve Skorlama

Severity seviyeleri

• Kritik Muhtemel özel credential, secret key veya yüksek etkili sabit gizli değer

• Yüksek Güçlü auth misuse, test credential, muhtemel bearer token veya servis seviyesi risk

• Orta Anlamlı ama bağlama bağlı güvenlik sinyali

• Düşük Yapılandırma görünürlüğü, referans, public key veya zayıf kanıt

Confidence mantığı

Confidence skoru 0-100 aralığındadır ve şu değişkenlerden etkilenir:

• desenin kuvveti
• bağlamın kalitesi
• anahtar tipinin niteliği
• placeholder olasılığı
• public veya publishable config olasılığı

Temel kategori seti

• Secret Exposure
• Token Pattern
• Auth Misuse
• Sensitive Endpoint Reference
• Cloud Config Exposure
• Client Storage Risk
• Test Artifact
• Environment Leak
• High Entropy Suspicion

Etik Kullanım Bildirimi

TokenTrace yalnızca pasif ve savunmacı analiz için tasarlanmıştır.

Bu araç yalnızca yetkili olduğunuz sistemlerde kullanılmalıdır.

Sınırlamalar

• sonuçlar regex ve bağlamsal sezgilerle üretilir
• minified dosyalarda satır doğruluğu düşebilir
• bazı public config değerleri zararsız olabilir
• her JWT benzeri yapı gerçek token değildir
• entropy bulguları hash, nonce veya build çıktısı olabilir
• yalnızca doğrudan referans verilen JS dosyaları incelenir

False Positive Notu

Her bulgu için Türkçe false positive açıklaması döndürülür. Özellikle şu senaryolarda manuel doğrulama şarttır:

• pk_live, pk_test gibi publishable key’ler
• Firebase istemci yapılandırmaları
• dokümantasyon veya demo amaçlı gömülü örnekler
• placeholder secret görünümleri
• minified bundle içindeki anlamsız entropy eşleşmeleri

Test Senaryoları

Hızlı smoke test

python -m compileall app
python run.py

Sonra:

http://127.0.0.1:8000
http://127.0.0.1:8000/about
http://127.0.0.1:8000/api/health

Basit örnek hedef

• https://example.com

Beklenen davranış:

• HTML çekilir
• JS referansı yoksa sıfır JS ile güvenli şekilde sonuç döner
• log alanı dolu gelir
• sonuç özeti düzgün üretilir

v2 Yol Haritası

Yakın hedefler

1. kalıcı analiz geçmişi
2. PDF rapor çıktısı
3. AST tabanlı JS bağlam analizi
4. özel detection profile desteği
5. allowlist ve ignore rule yönetimi
6. CI ve webhook entegrasyonu
7. budget heatmap widget
8. kategori bazlı mini chart widget
9. source footprint ve diff widget

Daha ileri hedefler

1. çoklu çalışma alanı
2. rol tabanlı rapor paylaşımı
3. analiz diff ve sürüm karşılaştırma
4. takım içi yorumlama akışı
5. ileri düzey görsel trend paneli

Son Not

TokenTrace, görünen her şeyi “kritik” ilan eden gürültülü bir tarayıcı olmamayı hedefler. İdeal kullanım biçimi, pasif görünürlüğü okunabilir hale getirmek ve geliştirici ile güvenlik ekipleri arasında ortak bir inceleme yüzeyi oluşturmaktır.