🛡️ ShadowDB - Data Privacy Proxy Layer

[English] | Türkçe

ShadowDB is a highly performant PostgreSQL TCP Proxy designed to protect sensitive data (PII) in development environments. It sits between your database client and the real database, intercepting traffic in real-time to anonymize sensitive fields (Emails, Phones, Secrets) on the fly without breaking the application logic.

It features a modern Real-time Dashboard to manage masking rules dynamically.

---

📸 Screenshots

Live Traffic Monitor	Schema Protection Rules
Real-time visualization of SQL queries	Toggle masking per column instantly

Audit Logs	Masked Data Result (PgAdmin)
Track who accessed what and when	Real data vs. ShadowDB masked data

---

🧠 How It Works (The "Magic")

ShadowDB is not just a UI; it's a low-level TCP Stream Processor.

1. TCP Interception (Man-in-the-Middle): ShadowDB opens a socket server on a custom port (e.g., 5433). When you connect your DB client (PgAdmin, DBeaver, or your App) to this port, ShadowDB accepts the connection and immediately opens a second connection to the real database (5432) on your behalf.

2. Packet Analysis: As data packets flow from the Real DB to your Client, ShadowDB inspects the binary stream. It looks for PostgreSQL DataRow messages.

3. Rules Engine & Regex: Based on the active rules in the Metadata Dashboard, it applies regex patterns to specific columns (e.g., email, phone).

4. Deterministic Masking (Consistent Hashing): Unlike simple "random" masking, ShadowDB uses a Seeded Hash Algorithm.

   • It calculates a unique shift value based on the character code and its position.
   • Result: user_1 will ALWAYS become xwnu_1.
   • Benefit: Developers can query WHERE email = 'xwnu_1...' and get consistent results during testing, while never knowing the real email.

---

🌍 Why ShadowDB? (Real World Scenarios)

🎭 Scenario 1: The "Outsource Team" Risk

Problem: You hired a remote freelance team to fix a bug. They need database access. Risk: Giving them access exposes all customer emails and passwords (KVKK/GDPR violation). Solution: Give them the ShadowDB Proxy IP. They see realistic but fake data. They fix the bug without ever complying with strict NDA procedures for data handling.

🐛 Scenario 2: The "Junior Developer" Accident

Problem: A junior developer runs SELECT * FROM users on their local machine, accidentally pulling 1,000,000 rows of PII to an insecure laptop. Solution: ShadowDB intercepts the query. Even if the laptop is stolen later, the data inside is mathematically generated gibberish, not real customer data.

---

📂 Project Structure

shadow-db/
├── apps/
│   ├── core/                  # 🧠 The Brain (TCP Proxy Server)
│   │   ├── src/index.ts       # Main Proxy Logic & Rule Engine
│   │   └── src/pg-packet-parser.ts # PostgreSQL Wire Protocol Parser
│   │
│   └── web/                   # 📊 The Face (Dashboard)
│       ├── app/page.tsx       # Main Dashboard with WebSockets
│       └── components/ui/     # Shadcn UI Components
│
└── logs/                      # 📜 Audit Logs (JSON format)

---

🚀 Getting Started

1. Installation

git clone https://github.com/your-username/shadow-db.git
cd shadow-db
npm install

2. Configuration (apps/core/.env)

PROXY_PORT=5433
DB_HOST=localhost
DB_PORT=5432   # Your REAL Database Port
DB_USER=postgres
DB_PASSWORD=password

3. Running

Terminal 1 (Proxy Engine):

npm run dev:core

Terminal 2 (Dashboard):

npm run dev:web

4. Connect

Point your database client to localhost:5433.

---

📜 MIT License

Distributed under the MIT License. See LICENSE for more information.

---

---

---

🛡️ ShadowDB - Veri Gizliliği ve Güvenlik Katmanı

ShadowDB, veritabanı ile kullanıcılarınız arasına giren akıllı bir Güvenlik Duvarıdır. Verileri bozmadan, sadece hassas kısımlarını (Email, T.C., Telefon) kişi bazlı olarak maskeler.

📸 Ekran Görüntüleri

Canlı Trafik İzleme	Şema Koruma Kuralları
Veritabanı trafiğini canlı izleyin	Hangi sütunun gizleneceğini seçin

Denetim Kayıtları (Audit)	Sonuç (PgAdmin)
Kim, ne zaman, ne sorguladı?	Maskelenmiş güvenli veri

---

🧠 Nasıl Çalışır? (Teknik Detay)

ShadowDB, basit bir arayüzden fazlasıdır; düşük seviyeli bir TCP Akış İşlemcisidir.

1. Araya Girme (Man-in-the-Middle): ShadowDB 5433 portunu dinlemeye başlar. Siz PgAdmin ile bu porta geldiğinizde, o da arka planda gerçek veritabanına (5432) bağlanır. İki uç arasında bir "boru" (pipe) oluşturur.

2. Paket Analizi: Borudan geçen veriyi bayt-bayt izler. PostgreSQL protokolündeki DataRow mesajlarını yakalar. Bu işlem sıfır gecikme (zero-latency) prensibiyle yapılır, yani uygulamanızı yavaşlatmaz.

3. Kural Motoru ve Regex: Dashboard üzerinden ayarladığınız kurallara (Örn: "Email sütununu gizle") göre, veritabanından dönen veri paketlerini anlık olarak değiştirir.

4. Deterministik Maskeleme (Tutarlı Şifreleme): Rastgele maskeleme yazılım test süreçlerini bozar. ShadowDB bunun yerine Tohumlu Hash (Seeded Hash) algoritması kullanır.

   • Algoritma: (Karakter Kodu + Pozisyon + Tohum) % Alfabe
   • Sonuç: Ahmet ismi her sorguda DAİMA Xkrzq olarak görünür.
   • Fayda: Yazılımcılar tutarlı veri ile test yapabilir ama gerçek kimliği asla bilemezler. "Bug #123 Xkrzq kullanıcısında oluyor" diyebilirler.

---

🌍 Neden ShadowDB? (Gerçek Senaryolar)

Modern yazılım geliştirmede güvenlik ve geliştirme hızı hep çakışır. ShadowDB bu sorunu çözer.

🎭 Senaryo 1: Outsource (Dış Kaynak) Ekipler

Sorun: Şirketinizdeki bir hatayı çözmesi için dışarıdan bir danışmanla anlaştınız. Hatayı çözmek için veritabanına bakmaları lazım. Risk: Veritabanını açarsanız tüm müşteri listenizi, telefon numaralarını ve özel bilgileri kopyalayabilirler. Bu KVKK/GDPR suçudur. Çözüm: Danışmana gerçek DB şifresini değil, ShadowDB Proxy adresini verirsiniz. Danışman sorgu attığında şunu görür:

• Gerçek: holding_ceo@sirket.com
• Danışmanın Gördüğü: hxqln_cxo@fxrmt.net Danışman hatayı çözer, kodunu yazar ama gerçek veriyi asla göremez.

🐛 Senaryo 2: Junior Developer Kazası

Sorun: Yeni işe giren bir yazılımcı, test yazarken yanlışlıkla canlı veritabanından 10.000 kullanıcının verisini kendi bilgisayarına çeker (SELECT * FROM users). Çözüm: ShadowDB devreye girer. "Email" ve "TC Kimlik" kolonlarını otomatik tanır. Junior developer'ın bilgisayarına inen veri tamamen maskelenmiş, anlamsız veridir. Laptop çalınsa bile içindeki veri çöp değerindedir.

---

📂 Proje ve Dosya Yapısı

Bu projeyi geliştirmek veya anlamak istiyorsanız, harita şöyledir:

shadow-db/
├── apps/
│   ├── core/                  # 🧠 Beyin (TCP Proxy Sunucusu)
│   │   ├── src/
│   │   │   ├── index.ts       # Ana motor. Bağlantıyı karşılar, veriyi işler, maskeler.
│   │   │   └── pg-packet-parser.ts # PostgreSQL dilinden anlayan tercüman. Veriyi analiz eder.
│   │   ├── .env               # Ayar dosyası (Hangi DB'ye bağlanacağız?).
│   │
│   └── web/                   # 📊 Yüz (Yönetim Paneli - Dashboard)
│       ├── app/
│       │   └── page.tsx       # WebSocket ile veriyi gösteren tek sayfalık uygulama.
│       ├── components/ui/     # Shadcn/ui bileşenleri (Button, Card, Table).
│
└── logs/                      # 📜 Denetim kayıtları (Audit Logs). JSON formatında saklanır.

---

🚀 Detaylı Kurulum Rehberi

Bu proje Node.js tabanlıdır ve herhangi bir PostgreSQL veritabanı ile çalışır.

1. İndirme

git clone https://github.com/kullaniciadiniz/shadow-db.git
cd shadow-db
npm install

2. Ayarlama

apps/core/ klasörü içine .env adında bir dosya oluşturun ve GERÇEK veritabanı bilgilerinizi girin:

PROXY_PORT=5433       # ShadowDB'nin dinleyeceği port
DB_HOST=localhost     # Gerçek DB adresi
DB_PORT=5432          # Gerçek DB portu
DB_USER=postgres      # Kullanıcı adı
DB_PASSWORD=sifreniz  # Şifre

3. Çalıştırma

Sistemi ayağa kaldırmak için iki terminale ihtiyacınız var.

Terminal 1 (Motoru Başlat):

npm run dev:core

> Çıktı: "ShadowDB Core v11.0 starting..."

Terminal 2 (Ekranı Başlat):

npm run dev:web

> Çıktı: "Ready in 2.5s"

4. Kullanım

1. Dashboard: Tarayıcıda http://localhost:3000 adresine gidin. Paneli göreceksiniz.
2. Bağlantı: Veritabanı programınızı (PgAdmin vb.) açın.
3. New Connection diyerek host kısmına localhost, Port kısmına 5433 yazın.
4. Bağlandınız! Artık attığınız her sorgu ShadowDB'den süzülerek geçecek.
5. Panelden "Schema & Rules" sekmesine gidip, hangi sütunun maskeleneceğini tek tıkla seçebilirsiniz.

---

📜 Lisans (MIT)

MIT Lisansı altında dağıtılmaktadır. Daha fazla bilgi için LICENSE dosyasına bakınız.