synapse-shield 0.1.0__py3-none-any.whl

synapse_shield/__init__.py

@@ -0,0 +1,4 @@
+from .middleware import shield_protect
+from .engine import SynapseEngine, analyze_behavior
+
+__all__ = ["shield_protect", "SynapseEngine", "analyze_behavior"]

synapse_shield/cli.py

@@ -0,0 +1,32 @@
+"""
+Synapse Shield CLI Runner
+"""
+
+import argparse
+import uvicorn
+
+def main():
+    parser = argparse.ArgumentParser(description="Synapse Shield - CLI Controller")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Run Server Command
+    run_parser = subparsers.add_parser("run", help="Start the Synapse Shield server and cockpit")
+    run_parser.add_argument("--host", default="0.0.0.0", help="Host address (default: 0.0.0.0)")
+    run_parser.add_argument("--port", type=int, default=8000, help="Port number (default: 8000)")
+
+    # Run Tests Command
+    subparsers.add_parser("test", help="Run the 7-vector Red Team bot attack simulator")
+
+    args = parser.parse_args()
+
+    if args.command == "run" or args.command is None:
+        port = getattr(args, "port", 8000)
+        host = getattr(args, "host", "0.0.0.0")
+        print(f"🛡️  Starting Synapse Shield on http://{host}:{port} ...")
+        uvicorn.run("synapse_shield.main:app", host=host, port=port, reload=True)
+    elif args.command == "test":
+        from .live_attacker import main as run_attack_suite
+        run_attack_suite()
+
+if __name__ == "__main__":
+    main()

synapse_shield/engine.py

@@ -0,0 +1,109 @@
+import math
+from typing import Dict, Any, List, Tuple
+from .features import extract_features
+
+def poisson_anomaly_score(k: int, lambda_val: float = 2.0) -> float:
+    if k <= 1:
+        return 0.0
+    cumulative_prob = 0.0
+    for i in range(k):
+        try:
+            term = (math.pow(lambda_val, i) * math.exp(-lambda_val)) / math.factorial(i)
+            cumulative_prob += term
+        except (OverflowError, ValueError):
+            break
+    return min(1.0, max(0.0, cumulative_prob))
+
+def analyze_behavior(telemetry: Dict[str, Any], recent_request_count: int = 1) -> Tuple[float, str, List[str], Dict[str, Any]]:
+    features = extract_features(telemetry)
+    reasons = []
+    total_risk = 0.0
+    
+    # 1. Webdriver Tespiti (Hard Block)
+    if features["webdriver"]:
+        total_risk += 100.0
+        reasons.append("Automation tool interface (navigator.webdriver) detected.")
+        
+    # 2. Ekran Boyutları (Headless)
+    if not features["screen_valid"]:
+        total_risk += 35.0
+        reasons.append("Invalid or headless screen dimensions detected.")
+        
+    # 3. Faresiz Form Etkileşimi
+    if (features["click_count"] > 0 or features["key_count"] > 0) and features["mouse_points"] == 0:
+        total_risk += 50.0
+        reasons.append("Interactive events occurred without mouse movement telemetry.")
+
+    # 4. Kinematik & Fitts Kanunu Analizi
+    if features["mouse_points"] > 5:
+        # A. Doğrusallık (Düz Çizgi Botları)
+        if features["total_distance"] > 30 and features["straightness"] > 0.985:
+            total_risk += 75.0
+            reasons.append(f"Euclidean straight-line trajectory detected (straightness: {features['straightness']:.4f}).")
+            
+        # B. Robotik Hız & İvme Varyansı
+        if features["total_distance"] > 30 and features["velocity_var"] < 0.0001:
+            total_risk += 65.0
+            reasons.append("Near-zero velocity variance observed in mouse path.")
+            
+        if features["total_distance"] > 30 and features["acceleration_var"] < 0.0001:
+            total_risk += 65.0
+            reasons.append("Near-zero acceleration variance observed in mouse path.")
+
+        # C. FITTS KANUNU KONTROLÜ (Hedefe Yaklaşırken Yavaşlamayan Botlar)
+        # İnsan bir hedefe/tıklamaya yaklaşırken hızını en az %60 düşürür (terminal_decel_ratio < 0.40)
+        if features["click_count"] > 0 and features["total_distance"] > 50:
+            if features["terminal_decel_ratio"] > 0.85:
+                total_risk += 45.0
+                reasons.append(f"Fitts's Law violation: Zero terminal deceleration before click ({features['terminal_decel_ratio']:.2f}).")
+
+        # D. İnsanüstü Hız
+        if features["max_velocity"] > 15.0:
+            total_risk += 40.0
+            reasons.append(f"Superhuman mouse velocity (max: {features['max_velocity']:.2f} px/ms).")
+
+    # 5. Klavye Dinamikleri
+    if features["key_count"] > 3:
+        if features["key_interval_var"] < 4.0:
+            total_risk += 60.0
+            reasons.append(f"Highly rhythmic typing pattern detected (variance: {features['key_interval_var']:.2f} ms²).")
+            
+        if features["key_interval_avg"] < 25.0:
+            total_risk += 50.0
+            reasons.append(f"Superhuman input frequency (avg typing interval: {features['key_interval_avg']:.1f} ms).")
+
+    # 6. Poisson Frekans Analizi & Biyometrik Füzyon
+    freq_anomaly = poisson_anomaly_score(recent_request_count, lambda_val=2.0)
+    if freq_anomaly >= 0.95:
+        is_human_telemetry = (
+            features["mouse_points"] > 5 
+            and features["straightness"] < 0.96 
+            and (features["velocity_var"] > 0.001 or features["avg_jerk"] > 0.0001)
+        )
+        if is_human_telemetry:
+            total_risk += 25.0 * freq_anomaly
+            reasons.append(f"High request frequency ({recent_request_count} req/10s), but organic human kinematics verified.")
+        else:
+            total_risk += 60.0 * freq_anomaly
+            reasons.append(f"Poisson request frequency anomaly (rate: {recent_request_count} req/10s, risk confidence: {freq_anomaly*100:.1f}%).")
+
+    bot_score = min(100.0, total_risk)
+    classification = "Bot" if bot_score >= 50.0 else "Human"
+    
+    if bot_score < 10.0:
+        reasons.append("Natural behavioral telemetry flags verified.")
+        
+    details = {
+        "features": features,
+        "recent_request_count": recent_request_count,
+        "poisson_anomaly_score": freq_anomaly
+    }
+    
+    return bot_score, classification, reasons, details
+
+class SynapseEngine:
+    def __init__(self, lambda_val: float = 2.0):
+        self.lambda_val = lambda_val
+
+    def analyze(self, telemetry: Dict[str, Any], recent_request_count: int = 1) -> Tuple[float, str, List[str], Dict[str, Any]]:
+        return analyze_behavior(telemetry, recent_request_count)

synapse_shield/features.py

@@ -0,0 +1,114 @@
+"""
+Synapse Shield - Kinematic Feature Extractor v0.2.0
+Extracts 19D physical motion vectors + Fitts's Law Deceleration Profiles.
+"""
+
+import math
+from typing import Dict, Any, List
+
+def extract_features(telemetry: Dict[str, Any]) -> Dict[str, Any]:
+    features = {
+        "mouse_points": 0,
+        "total_distance": 0.0,
+        "straightness": 1.0,
+        "avg_velocity": 0.0,
+        "max_velocity": 0.0,
+        "velocity_var": 0.0,
+        "avg_acceleration": 0.0,
+        "acceleration_var": 0.0,
+        "avg_jerk": 0.0,
+        "click_count": 0,
+        "key_count": 0,
+        "key_interval_avg": 0.0,
+        "key_interval_var": 0.0,
+        "webdriver": False,
+        "screen_valid": True,
+        "scroll_count": 0,
+        "terminal_decel_ratio": 1.0,  # Fitts Kanunu: Son hız / Tepe hız oranı
+        "velocity_skewness": 0.0,     # Hız profilinin asimetrisi (Balistik vs Düzeltici)
+    }
+
+    # Tarayıcı Nitelikleri
+    browser = telemetry.get("browser", {})
+    features["webdriver"] = bool(browser.get("webdriver", False))
+    
+    screen_width = browser.get("screen_width", 0)
+    screen_height = browser.get("screen_height", 0)
+    if screen_width <= 0 or screen_height <= 0:
+        features["screen_valid"] = False
+
+    features["scroll_count"] = len(telemetry.get("scrolls", []))
+    features["click_count"] = len(telemetry.get("clicks", []))
+
+    # Klavye Dinamikleri
+    keystrokes = telemetry.get("keystrokes", [])
+    features["key_count"] = len(keystrokes)
+    if len(keystrokes) > 1:
+        sorted_keys = sorted(keystrokes, key=lambda k: k.get("t", 0))
+        intervals = [max(0.0, sorted_keys[i].get("t", 0) - sorted_keys[i - 1].get("t", 0)) for i in range(1, len(sorted_keys))]
+        if intervals:
+            avg_int = sum(intervals) / len(intervals)
+            features["key_interval_avg"] = avg_int
+            features["key_interval_var"] = sum((x - avg_int) ** 2 for x in intervals) / len(intervals)
+
+    # Fare Hareketi ve Fitts Kanunu Kinematiği
+    mouse_movements = telemetry.get("mouse_movements", [])
+    features["mouse_points"] = len(mouse_movements)
+    
+    if len(mouse_movements) > 2:
+        movements = sorted(mouse_movements, key=lambda m: m.get("t", 0))
+        
+        distances, dts, velocities = [], [], []
+        start_x, start_y = movements[0].get("x", 0), movements[0].get("y", 0)
+        end_x, end_y = movements[-1].get("x", 0), movements[-1].get("y", 0)
+        displacement = math.sqrt((end_x - start_x)**2 + (end_y - start_y)**2)
+        
+        for i in range(1, len(movements)):
+            x1, y1, t1 = movements[i-1].get("x", 0), movements[i-1].get("y", 0), movements[i-1].get("t", 0)
+            x2, y2, t2 = movements[i].get("x", 0), movements[i].get("y", 0), movements[i].get("t", 0)
+            
+            d_dist = math.sqrt((x2 - x1)**2 + (y2 - y1)**2)
+            d_time = max(0.1, t2 - t1)
+            
+            distances.append(d_dist)
+            dts.append(d_time)
+            velocities.append(d_dist / d_time)
+        
+        total_dist = sum(distances)
+        features["total_distance"] = total_dist
+        features["straightness"] = (displacement / total_dist) if total_dist > 0 else 1.0
+            
+        if velocities:
+            avg_vel = sum(velocities) / len(velocities)
+            max_vel = max(velocities)
+            features["avg_velocity"] = avg_vel
+            features["max_velocity"] = max_vel
+            features["velocity_var"] = sum((v - avg_vel) ** 2 for v in velocities) / len(velocities)
+            
+            # FITTS KANUNU 1: Son %20'lik Yoldaki Yavaşlama Oranı
+            last_segment_count = max(1, int(len(velocities) * 0.25))
+            terminal_avg_vel = sum(velocities[-last_segment_count:]) / last_segment_count
+            features["terminal_decel_ratio"] = (terminal_avg_vel / max_vel) if max_vel > 0 else 1.0
+            
+            # FITTS KANUNU 2: Hızın Tepe Noktası Konumu (Skewer / Asimetri)
+            peak_idx = velocities.index(max_vel)
+            features["velocity_skewness"] = peak_idx / float(len(velocities)) # İnsanda 0.25 - 0.45 arası
+            
+            # İvme ve Jerk (Sarsıntı) Hesabı
+            accelerations = []
+            for i in range(1, len(velocities)):
+                accelerations.append((velocities[i] - velocities[i-1]) / dts[i])
+                
+            if accelerations:
+                avg_acc = sum(accelerations) / len(accelerations)
+                features["avg_acceleration"] = avg_acc
+                features["acceleration_var"] = sum((a - avg_acc) ** 2 for a in accelerations) / len(accelerations)
+                
+                jerks = []
+                for i in range(1, len(accelerations)):
+                    jerks.append((accelerations[i] - accelerations[i-1]) / dts[i+1])
+                
+                if jerks:
+                    features["avg_jerk"] = sum(map(abs, jerks)) / len(jerks)
+
+    return features

synapse_shield/live_attacker.py

@@ -0,0 +1,128 @@
+"""
+Synapse Shield - Red Team Automated Bot Attack Suite v0.2.0
+Simulates 7 real-world bot attack campaigns including Replay Attacks.
+"""
+
+import time
+import math
+import random
+import json
+import base64
+import urllib.request
+import urllib.error
+
+TARGET_URL = "http://127.0.0.1:8000/api/score"
+CHALLENGE_URL = "http://127.0.0.1:8000/api/challenge"
+
+class C:
+    RED = '\033[91m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    CYAN = '\033[96m'
+    BOLD = '\033[1m'
+    END = '\033[0m'
+
+def get_challenge():
+    try:
+        with urllib.request.urlopen(CHALLENGE_URL) as resp:
+            return json.loads(resp.read().decode('utf-8')).get("challenge")
+    except Exception:
+        return None
+
+def send_attack(name: str, payload: dict, ip_suffix: int = 1) -> dict:
+    data = json.dumps(payload).encode('utf-8')
+    req = urllib.request.Request(
+        TARGET_URL,
+        data=data,
+        headers={
+            'Content-Type': 'application/json',
+            'User-Agent': f'SynapseShield-RedTeamBot/2.0 ({name})',
+            'x-forwarded-for': f'192.168.1.{ip_suffix}'
+        }
+    )
+    t_start = time.perf_counter()
+    try:
+        with urllib.request.urlopen(req) as resp:
+            t_end = time.perf_counter()
+            res = json.loads(resp.read().decode('utf-8'))
+            res['network_latency_ms'] = round((t_end - t_start) * 1000, 2)
+            return res
+    except Exception as e:
+        return {"status": "error", "bot_score": 100.0, "classification": "Bot", "reasons": [str(e)]}
+
+def print_result(attack_num: int, title: str, res: dict, expected_blocked: bool = True):
+    score = res.get("bot_score", 0.0)
+    classification = res.get("classification", "Unknown")
+    reasons = res.get("reasons", [])
+    latency = res.get("network_latency_ms", 0.0)
+    
+    is_blocked = (classification == "Bot" or score >= 50.0)
+    success = is_blocked if expected_blocked else not is_blocked
+    status_text = f"{C.GREEN}✅ KALKAN BAŞARILI (Engellendi){C.END}" if success else f"{C.RED}❌ BAŞARISIZ{C.END}"
+
+    print(f"\n{C.BOLD}{C.CYAN}┌─────────────────────────────────────────────────────────────{C.END}")
+    print(f"{C.BOLD}{C.CYAN}│ SALDIRI #{attack_num}: {title}{C.END}")
+    print(f"{C.BOLD}{C.CYAN}├─────────────────────────────────────────────────────────────{C.END}")
+    print(f"│  Durum:        {status_text}")
+    print(f"│  Karar:        {C.RED if is_blocked else C.GREEN}{classification.upper()}{C.END} (Risk: {score:.1f}%)")
+    print(f"│  Ağ Gecikmesi: {C.YELLOW}{latency} ms{C.END}")
+    print(f"│  Nedenler:     {', '.join(reasons)}")
+    print(f"{C.BOLD}{C.CYAN}└─────────────────────────────────────────────────────────────{C.END}")
+
+def main():
+    print(f"\n{C.BOLD}{C.YELLOW}╔═════════════════════════════════════════════════════════════╗{C.END}")
+    print(f"{C.BOLD}{C.YELLOW}║   🔴 SYNAPSE SHIELD v0.2.0 — RED TEAM BOT SALDIRI SÜİTİ     ║{C.END}")
+    print(f"{C.BOLD}{C.YELLOW}╚═════════════════════════════════════════════════════════════╝{C.END}\n")
+
+    # 1. Selenium
+    res1 = send_attack("Selenium", {"browser": {"webdriver": True, "screen_width": 800, "screen_height": 600}}, ip_suffix=10)
+    print_result(1, "Selenium Headless Crawler", res1, expected_blocked=True)
+
+    # 2. Linear Mouse
+    t = int(time.time()*1000)
+    res2 = send_attack("Linear", {"mouse_movements": [{"x": 50 + i*30, "y": 50 + i*20, "t": t + i*20} for i in range(25)]}, ip_suffix=20)
+    print_result(2, "Doğrusal Fare Botu (Straight-Line)", res2, expected_blocked=True)
+
+    # 3. Bézier
+    p0, p1, p2 = (50, 50), (400, 700), (900, 200)
+    bezier_pts = [{"x": round((1-i/30)**2 * p0[0] + 2*(1-i/30)*(i/30)*p1[0] + (i/30)**2 * p2[0]),
+                   "y": round((1-i/30)**2 * p0[1] + 2*(1-i/30)*(i/30)*p1[1] + (i/30)**2 * p2[1]),
+                   "t": t + i*20} for i in range(30)]
+    res3 = send_attack("Bezier", {"mouse_movements": bezier_pts}, ip_suffix=30)
+    print_result(3, "Bézier Eğrisi Botu (No-Jerk Curve)", res3, expected_blocked=True)
+
+    # 4. Auto-Typer
+    keys = [{"type": "down", "t": t + i*100} for i in range(10)]
+    res4 = send_attack("AutoTyper", {"keystrokes": keys, "clicks": [{"x": 100, "y": 100, "t": t}]}, ip_suffix=40)
+    print_result(4, "Robotik Klavye Otomatı", res4, expected_blocked=True)
+
+    # 5. Poisson Flood
+    for _ in range(7):
+        send_attack("Flood", {"browser": {}}, ip_suffix=50)
+        time.sleep(0.01)
+    res5 = send_attack("Flood", {"browser": {}}, ip_suffix=50)
+    print_result(5, "Poisson İstek Bombardımanı (DDoS)", res5, expected_blocked=True)
+
+    # 6. Doğal İnsan
+    human_pts = [{"x": round(100 + i*15 + random.gauss(0, 2.5)), "y": round(150 + math.sin(i/3)*20 + random.gauss(0, 2.5)), "t": t + i*25} for i in range(40)]
+    res6 = send_attack("Human", {"mouse_movements": human_pts, "clicks": [{"x": 700, "y": 200, "t": t+1000}]}, ip_suffix=60)
+    print_result(6, "Doğal İnsan Ziyaretçisi (Control)", res6, expected_blocked=False)
+
+    # 7. YENİ: Replay Attack Simülasyonu
+    print(f"\n{C.YELLOW}[*] Replay Attack Testi: Gerçek bir token çalınıp 2. kez gönderiliyor...{C.END}")
+    ch = get_challenge()
+    if ch:
+        Date_now = int(time.time())
+        envelope = {"challenge": ch, "telemetry": {"mouse_movements": human_pts}, "created_at": Date_now}
+        valid_token = base64.b64encode(json.dumps(envelope).encode()).decode()
+        
+        # 1. Gönderim (Başarılı olmalı)
+        send_attack("Replay-1", {"token": valid_token}, ip_suffix=70)
+        # 2. Gönderim (Replay - ENGELLENMELİ!)
+        res7 = send_attack("Replay-2", {"token": valid_token}, ip_suffix=70)
+        print_result(7, "Replay Attack (Aynı Token'ı Tekrar Kullanma)", res7, expected_blocked=True)
+
+    print(f"\n{C.BOLD}{C.GREEN}🎯 TÜM 7 SALDIRI VE GÜVENLİK TESTİ BAŞARIYLA TAMAMLANDI!{C.END}\n")
+
+if __name__ == "__main__":
+    main()

synapse_shield/main.py

@@ -0,0 +1,196 @@
+import os
+import json
+import sqlite3
+import uvicorn
+from datetime import datetime, timedelta
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.responses import HTMLResponse, FileResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from typing import Dict, Any, List
+
+from .engine import analyze_behavior
+from .tokens import generate_challenge, verify_and_consume_token
+
+DB_FILE = "synapse_shield.db"
+
+def init_db():
+    conn = sqlite3.connect(DB_FILE)
+    cursor = conn.cursor()
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS logs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT,
+            ip TEXT,
+            user_agent TEXT,
+            bot_score REAL,
+            classification TEXT,
+            reasons TEXT,
+            features TEXT,
+            telemetry TEXT
+        )
+    """)
+    cursor.execute("PRAGMA journal_mode=WAL;")
+    conn.commit()
+    conn.close()
+
+init_db()
+
+app = FastAPI(title="Synapse Shield - Behavioral Bot Detection Engine")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+TRUSTED_PROXIES = {"127.0.0.1", "::1"}
+
+def get_client_ip(request: Request) -> str:
+    client_ip = request.client.host if request.client else "127.0.0.1"
+    if client_ip in TRUSTED_PROXIES:
+        forwarded = request.headers.get("x-forwarded-for")
+        if forwarded:
+            return forwarded.split(",")[0].strip()
+    return client_ip
+
+def get_recent_request_count(ip: str) -> int:
+    conn = sqlite3.connect(DB_FILE)
+    cursor = conn.cursor()
+    ten_seconds_ago = (datetime.utcnow() - timedelta(seconds=10)).isoformat()
+    cursor.execute("SELECT COUNT(*) FROM logs WHERE ip = ? AND timestamp > ?", (ip, ten_seconds_ago))
+    count = cursor.fetchone()[0]
+    conn.close()
+    return count + 1
+
+def save_log(ip: str, user_agent: str, bot_score: float, classification: str, reasons: List[str], features: Dict[str, Any], telemetry: Dict[str, Any]):
+    conn = sqlite3.connect(DB_FILE)
+    cursor = conn.cursor()
+    now = datetime.utcnow().isoformat()
+    cursor.execute(
+        """
+        INSERT INTO logs (timestamp, ip, user_agent, bot_score, classification, reasons, features, telemetry)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (now, ip, user_agent, bot_score, classification, json.dumps(reasons), json.dumps(features), json.dumps(telemetry))
+    )
+    conn.commit()
+    conn.close()
+
+# YENİ ENDPOINT: İstemciye tek kullanımlık challenge verir
+@app.get("/api/challenge")
+async def get_challenge():
+    return generate_challenge()
+
+@app.post("/api/score")
+async def score_telemetry(request: Request):
+    try:
+        body = await request.json()
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid JSON payload")
+
+    ip = get_client_ip(request)
+    user_agent = request.headers.get("user-agent", "Unknown")
+
+    # 1. Kriptografik Token Varsa Doğrula
+    if "token" in body:
+        is_valid, reason, telemetry = verify_and_consume_token(body["token"])
+        if not is_valid:
+            # Replay Attack veya sahte token durumu
+            save_log(ip, user_agent, 100.0, "Bot", [reason], {}, {})
+            return {
+                "status": "blocked",
+                "bot_score": 100.0,
+                "classification": "Bot",
+                "reasons": [reason],
+                "details": {}
+            }
+    else:
+        # Geriye dönük uyumluluk: doğrudan telemetri gönderildiyse
+        telemetry = body.get("telemetry", body)
+
+    recent_count = get_recent_request_count(ip)
+    bot_score, classification, reasons, details = analyze_behavior(telemetry, recent_count)
+    save_log(ip, user_agent, bot_score, classification, reasons, details.get("features", {}), telemetry)
+
+    return {
+        "status": "success",
+        "bot_score": bot_score,
+        "classification": classification,
+        "reasons": reasons,
+        "details": details
+    }
+
+@app.get("/api/logs")
+async def get_logs(limit: int = 50):
+    conn = sqlite3.connect(DB_FILE)
+    conn.row_factory = sqlite3.Row
+    cursor = conn.cursor()
+    cursor.execute("SELECT id, timestamp, ip, user_agent, bot_score, classification, reasons, features FROM logs ORDER BY id DESC LIMIT ?", (limit,))
+    rows = cursor.fetchall()
+    
+    recent_logs = []
+    for r in rows:
+        recent_logs.append({
+            "id": r["id"],
+            "timestamp": r["timestamp"],
+            "ip": r["ip"],
+            "user_agent": r["user_agent"],
+            "bot_score": r["bot_score"],
+            "classification": r["classification"],
+            "reasons": json.loads(r["reasons"]) if r["reasons"] else [],
+            "features": json.loads(r["features"]) if r["features"] else {}
+        })
+        
+    cursor.execute("SELECT COUNT(*) FROM logs")
+    total_requests = cursor.fetchone()[0]
+    cursor.execute("SELECT COUNT(*) FROM logs WHERE classification = 'Bot'")
+    bot_requests = cursor.fetchone()[0]
+    cursor.execute("SELECT AVG(bot_score) FROM logs WHERE classification = 'Bot'")
+    avg_bot = cursor.fetchone()[0] or 0.0
+    cursor.execute("SELECT AVG(bot_score) FROM logs WHERE classification = 'Human'")
+    avg_human = cursor.fetchone()[0] or 0.0
+    conn.close()
+    
+    return {
+        "total_requests": total_requests,
+        "bot_requests": bot_requests,
+        "human_requests": total_requests - bot_requests,
+        "bot_ratio": (bot_requests / total_requests * 100) if total_requests > 0 else 0.0,
+        "avg_bot_score": round(avg_bot, 2),
+        "avg_human_score": round(avg_human, 2),
+        "logs": recent_logs
+    }
+
+@app.post("/api/clear")
+async def clear_logs():
+    conn = sqlite3.connect(DB_FILE)
+    cursor = conn.cursor()
+    cursor.execute("DELETE FROM logs")
+    conn.commit()
+    conn.close()
+    return {"status": "success", "message": "Database logs cleared"}
+
+STATIC_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "static")
+
+@app.get("/")
+def read_root():
+    index_path = os.path.join(STATIC_DIR, "index.html")
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    return HTMLResponse("<h2>Synapse Shield Cockpit: index.html missing.</h2>")
+
+@app.get("/static/synapse-sdk.js")
+def read_sdk():
+    sdk_path = os.path.join(STATIC_DIR, "synapse-sdk.js")
+    if os.path.exists(sdk_path):
+        return FileResponse(sdk_path, media_type="application/javascript")
+    return HTMLResponse("<h2>synapse-sdk.js missing.</h2>", status_code=404)
+
+if os.path.exists(STATIC_DIR):
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+if __name__ == "__main__":
+    uvicorn.run("synapse_shield.main:app", host="0.0.0.0", port=8000, reload=True)

synapse_shield/middleware.py

@@ -0,0 +1,59 @@
+"""
+Synapse Shield - Drop-in FastAPI / Python Middleware
+Allows developers to protect any route with a single decorator: @shield_protect
+"""
+
+from functools import wraps
+from fastapi import Request, HTTPException
+from .engine import analyze_behavior
+
+def shield_protect(max_risk_score: float = 50.0):
+    """
+    Decorator to protect any FastAPI endpoint with Synapse Shield behavioral biometrics.
+    Usage:
+        @app.post("/login")
+        @shield_protect(max_risk_score=50.0)
+        async def login(request: Request):
+            ...
+    """
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Extract request object
+            request: Request = kwargs.get("request")
+            if not request:
+                for arg in args:
+                    if isinstance(arg, Request):
+                        request = arg
+                        break
+
+            if not request:
+                raise HTTPException(status_code=500, detail="Request object not found in endpoint signature")
+
+            # Extract telemetry from header or body
+            telemetry = None
+            try:
+                body = await request.json()
+                telemetry = body.get("telemetry") or body
+            except Exception:
+                pass
+
+            if not telemetry:
+                raise HTTPException(status_code=403, detail="[Synapse Shield] Missing behavioral telemetry payload.")
+
+            bot_score, classification, reasons, _ = analyze_behavior(telemetry)
+
+            if bot_score >= max_risk_score:
+                raise HTTPException(
+                    status_code=403, 
+                    detail={
+                        "error": "Access Denied by Synapse Shield",
+                        "classification": classification,
+                        "bot_score": f"{bot_score}%",
+                        "reasons": reasons
+                    }
+                )
+
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator