⚡ Overview

Synapse Shield replaces intrusive legacy CAPTCHAs and expensive proprietary cloud WAFs with sub-millisecond behavioral biomechanics.

By evaluating natural human neuromuscular micro-tremors (Jerk: $\frac{da}{dt}$), Fitts's Law terminal deceleration profiles, cursor curvature, and millisecond keystroke dynamics, Synapse Shield autonomously classifies and mitigates bots, scrapers, and credential stuffers before they touch your backend logic.

✨ Key Features & Security Architecture (v0.8.0)

🏛️ Architecture & Sequence Diagram

┌─────────────────┐             ┌─────────────────────┐             ┌─────────────────────────┐
│  Client Browser │             │  FastAPI Gateway    │             │  Kinematic Decision     │
│  (synapse-sdk)  │             │  (Synapse Shield)   │             │  Engine (<0.5ms SLA)    │
└────────┬────────┘             └──────────┬──────────┘             └────────────┬────────────┘
         │                                 │                                     │
         │── 1. GET /api/challenge ───────►│                                     │
         │◄── 2. { nonce, ts, hmac_sig } ──│  (Generates single-use signed nonce)│
         │                                 │                                     │
   [User moves cursor / types]             │                                     │
   [SDK bundles 50Hz telemetry]            │                                     │
         │                                 │                                     │
         │── 3. POST /api/score {token} ──►│  (1. Validates HMAC signature)      │
         │                                 │  (2. Checks 60s TTL freshness)      │
         │                                 │  (3. Checks Replay Attack nonce)    │
         │                                 │                                     │
         │                                 │── 4. asyncio.to_thread ────────────►│ (19D Kinematics)
         │                                 │                                     │ (Jerk & Fitts's Law)
         │                                 │                                     │ (Poisson Anomaly)
         │                                 │◄── 5. (bot_score, ALLOW/BLOCK) ─────│
         │                                 │                                     │
         │                                 │── 6. Save Log to SQLite (WAL)       │
         │◄── 7. HTTP 200 {ALLOW/BLOCK} ───│                                     │

🚀 30-Second Quickstart

Option 1: Install via PyPI

pip install synapse-shield

Run the server and live cockpit directly from your terminal:

synapse-shield run --port 8000

Run the automated 7-vector adversarial security test suite:

synapse-shield test

Retrain the 1D-CNN AI model autonomously on local SQLite telemetry (Active Learning):

synapse-shield retrain --epochs 5 --lr 0.01

Option 2: Clone & Local Development

git clone https://github.com/0xStoic-bit/Synapse_Shield.git
cd Synapse_Shield
pip install -e .
python test_suite.py

Visit http://127.0.0.1:8000 in your browser to launch the Live Security Cockpit.

Option 3: Docker Deployment (Recommended)

Run the entire Synapse Shield stack, including the backend engine, SQLite WAL persistence, and the telemetry collector in a single container.

# Start the container in detached mode
docker-compose up -d

# View real-time logs
docker-compose logs -f

The Synapse API and Live Cockpit will be available at http://localhost:8000.

🚨 Real-time Webhook Alerts (Telegram & Discord)

Synapse Shield features zero-latency background webhook notifications. When a critical threat is blocked (e.g., STEALTH_AUTOMATION, POISSON_FLOOD), you receive an instant alert on your phone.

Setting up Telegram Alerts

1. Open Telegram and message @BotFather with /newbot.
2. Follow the steps to get your HTTP API Token (e.g., 123456:ABC-DEF...).
3. Send a message like "Hello" to your newly created bot to initialize the chat.
4. Message @userinfobot and press START to get your Chat ID (e.g., 123456789).
5. Open the Synapse Shield Cockpit (http://127.0.0.1:8000), click WEBHOOKS, and paste your Token and Chat ID.

Setting up Discord Alerts

1. Go to your Discord Server settings > Integrations > Webhooks > New Webhook.
2. Copy the Webhook URL.
3. Open the Synapse Shield Cockpit, click WEBHOOKS, and paste the URL.

💻 Developer Integration

1. FastAPI Integration

Protect any API endpoint using the @shield_protect decorator or global middleware:

from fastapi import FastAPI, Request
from synapse_shield import shield_protect, SynapseShieldMiddleware

app = FastAPI()
app.add_middleware(SynapseShieldMiddleware, protected_paths=["/api/auth"])

@app.post("/api/login")
@shield_protect(max_risk_score=50.0, accessibility_mode=False)
async def login(request: Request):
    return {"status": "authenticated"}

2. Django & Flask Integration

Native support for Django and Flask environments.

Django (settings.py):

MIDDLEWARE = [
    # ...
    'synapse_shield.django.SynapseShieldMiddleware',
]
SYNAPSE_SHIELD_PROTECTED_PATHS = ['/api/login']
SYNAPSE_SHIELD_MAX_RISK = 50.0
SYNAPSE_SHIELD_ACCESSIBILITY = False

Flask:

from flask import Flask
from synapse_shield.flask import shield_protect_flask

app = Flask(__name__)

@app.route("/login", methods=["POST"])
@shield_protect_flask(max_risk_score=50.0)
def login():
    return {"status": "authenticated"}

3. React / Next.js Integration

We provide a drop-in "use client" compatible React package.

import { useSynapseShield, SynapseProtect } from 'synapse-shield-react';

export default function LoginForm() {
  const { getProtectedPayload } = useSynapseShield();

  const handleSubmit = async (e) => {
    e.preventDefault();
    const payload = getProtectedPayload();
    // Send payload.token to your backend
  };

  return (
    <form onSubmit={handleSubmit}>
      <SynapseProtect />
      <button type="submit">Login</button>
    </form>
  );
}

4. Vue 3 / Nuxt 3 Integration

Official Vue 3 composable and component package (synapse-shield-vue). Fully SSR-safe for Nuxt 3.

<script setup>
import { ref } from 'vue';
import { useSynapseShield, SynapseProtect } from 'synapse-shield-vue';

const { getProtectedPayload } = useSynapseShield();
const username = ref('');
const password = ref('');

const handleSubmit = async () => {
  const payload = getProtectedPayload();
  // Submit payload.token to backend
};
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <SynapseProtect />
    <input v-model="username" type="text" placeholder="Username" />
    <input v-model="password" type="password" placeholder="Password" />
    <button type="submit">Login</button>
  </form>
</template>

5. Prometheus Metrics

Enterprise observability out of the box. Automatically exposes latency and block rates. To enable multi-process support (e.g., Gunicorn workers), set the environment variable:

export PROMETHEUS_MULTIPROC_DIR=/tmp/synapse_metrics

5. Vanilla JS / HTML SDK

Add the lightweight SDK (<5 KB) to your vanilla project:

<script src="http://localhost:8000/static/synapse-sdk.js"></script>
<script>
  SynapseShield.init();
  async function handleLogin() {
    const payload = SynapseShield.getPayload();
    // Submit payload
  }
</script>

🤖 Attack Simulation Benchmarks

Run the full adversarial suite anytime:

synapse-shield test

🧠 Kinematic & Mathematical Foundations

1. Jerk — Neuromuscular Tremor Fingerprint

$$\text{Jerk} = \frac{da}{dt} = \frac{d^3x}{dt^3}$$

Human muscle tremors produce continuous high-frequency Jerk. Mathematical bot curves (Bézier/Linear) produce near-zero or static Jerk.

2. Fitts's Law Terminal Deceleration Index

$$\text{Terminal Decel Ratio} = \frac{\bar{v}{\text{terminal (last 25%)}}}{v{\text{peak}}}$$

Humans naturally decelerate ($< 0.40$) as they approach the target click point.

3. Cumulative Poisson Anomaly Distribution

$$P(X < k) = \sum_{i=0}^{k-1} \frac{\lambda^i e^{-\lambda}}{i!}$$

📁 Repository Structure

Synapse_Shield/
├── .github/
│   └── workflows/
│       └── ci.yml             # Automated CI matrix (Python 3.10, 3.11, 3.12)
├── src/
│   └── synapse_shield/
│       ├── __init__.py        # Public API exports
│       ├── cli.py             # CLI Controller (run / test commands)
│       ├── engine.py          # Real-time Decision & Poisson Engine
│       ├── features.py        # 19D Kinematics, Fitts's Law & Multimodal Tokenizer
│       ├── models.py          # Zero-Dependency NumPy 1D-CNN Inference Engine
│       ├── weights.npz        # 4KB Serialized Neural Network Weights
│       ├── main.py            # Async FastAPI Gateway & SQLite Logger
│       ├── middleware.py      # @shield_protect & Middleware classes
│       ├── django.py          # Django Middleware Adapter
│       ├── flask.py           # Flask Route Decorator
│       ├── metrics.py         # Prometheus Multi-Process Exporter
│       ├── tokens.py          # HMAC-SHA256 Challenge & Replay Defense
│       ├── train.py           # Zero-Dependency NumPy Active Learning Pipeline
│       ├── live_attacker.py   # 7-Vector Red Team Simulation Suite
│       └── static/            # Embedded 3D Cockpit & Client SDK
│           ├── index.html
│           └── synapse-sdk.js
├── synapse-shield-react/      # React / Next.js SDK Package
│   ├── src/
│   │   ├── SynapseProtect.tsx # "use client" Drop-in Component
│   │   ├── useSynapseShield.ts# React Hook with event throttling
│   │   └── index.ts
│   ├── package.json
│   └── tsconfig.json
├── tests/                     # Modular Pytest Suite
│   ├── test_features.py
│   ├── test_tokens.py
│   ├── test_engine.py
│   └── test_api.py
├── test_suite.py              # Standalone Zero-Dependency Test Runner
├── pyproject.toml             # PEP 517/621 Package Definition
├── requirements.txt           # Core Dependencies
├── LICENSE                    # MIT License
└── README.md

📜 License

Distributed under the MIT License. Free for commercial and personal use.