👻 GhostID

Continuous Behavioral Session Verification — Zero Friction for Real Users

Drop one script into any web app. GhostID silently verifies whether the person currently typing is the same person who logged in. Only impostors get interrupted.

Built by Yogesh Rayal

What It Does · Architecture · ML Pipeline · Quick Start · Benchmarks · Security · Deploy

🧠 What It Does

Traditional session security breaks the moment a session token is stolen or a user steps away from their device. GhostID solves this without cameras, OTPs, or user friction.

After login, GhostID runs silently in the background. Every 60 seconds (configurable), it extracts a 41-feature keystroke vector from the user's typing and compares it against their enrolled behavioral baseline using an LSTM encoder + cosine similarity.

The result is a confidence score from 0–100 that maps to one of four tiers:

Score	Tier	Action
85–100	`✅ SILENT_PASS`	Session continues — user never knows GhostID ran
70–84	`💬 SOFT_NUDGE`	One-tap confirm ("Still you?")
40–69	`⌨️ TYPING_CHALLENGE`	Re-verify by typing a short phrase
0–39	`🔴 HARD_STOP`	Session terminated — full re-authentication required

No camera. No OTP. No friction for real users. Only impostors get stopped.

🎯 Use Cases

Domain	Threat Addressed
🎓 Online Exams	Mid-exam handoff to a different person
🏢 Corporate / HR	Ghost employees clocking in for absent colleagues
🏦 Fintech / Banking	Cookie hijacking before high-value transactions
🏥 Healthcare / EHR	Shared workstation walk-away identity exposure
🔐 SaaS Platforms	Credential sharing across multiple users

🏗️ Architecture

GhostID is a four-layer system: a browser SDK, a FastAPI inference backend, an ONNX encoder, and a scoring engine.

╔══════════════════════════════════════════════════════════════════╗
║                        USER'S BROWSER                           ║
║                                                                  ║
║   ┌──────────────────────────────────────────────────────────┐   ║
║   │                    ghostid.js (SDK)                     │   ║
║   │                                                          │   ║
║   │  • Passively captures keystroke press/release timings   │   ║
║   │  • Extracts 41 behavioral features per window           │   ║
║   │  • Runs comparison every 60s (tunable interval)         │   ║
║   │  • Reacts to tier decision (nudge / challenge / stop)   │   ║
║   └──────────────────────┬───────────────────────────────────┘   ║
╚═════════════════════════╪════════════════════════════════════════╝
                          │
              POST /enroll  (×2 for baseline)
              POST /score   (every 60 seconds)
                          │
                          ▼
╔══════════════════════════════════════════════════════════════════╗
║                   FASTAPI BACKEND (Python)                      ║
║                                                                  ║
║   ┌──────────────────────────────────────────────────────────┐   ║
║   │  Auth & Rate Limiting                                   │   ║
║   │  • API key via X-GhostID-Key header                     │   ║
║   │  • 100 req/min per user (configurable)                  │   ║
║   ├──────────────────────────────────────────────────────────┤   ║
║   │  Feature Processing                                     │   ║
║   │  • Normalize 41 features with saved scaler_params.json  │   ║
║   │  • Fernet-encrypt embeddings before SQLite storage      │   ║
║   └──────────────────────┬───────────────────────────────────┘   ║
╚═════════════════════════╪════════════════════════════════════════╝
                          │
                          ▼
╔══════════════════════════════════════════════════════════════════╗
║                  ONNX ENCODER (Inference)                       ║
║                                                                  ║
║   Input  → 41 scaled keystroke features                         ║
║   Model  → Bidirectional LSTM → 128-dim bottleneck              ║
║   Output → 128-dim L2-normalized behavioral embedding           ║
║   Size   → ~60 KB  |  Latency → <1ms CPU inference             ║
╚═════════════════════════╪════════════════════════════════════════╝
                          │
                          ▼
╔══════════════════════════════════════════════════════════════════╗
║               SIMILARITY SCORING & TIER ENGINE                  ║
║                                                                  ║
║   • Cosine similarity: live embedding vs. enrolled baseline     ║
║   • Scale raw similarity → 0–100 confidence score              ║
║   • Map score → [SILENT_PASS | SOFT_NUDGE | CHALLENGE | STOP]  ║
║   • Return action decision to browser SDK                       ║
╚══════════════════════════════════════════════════════════════════╝

Data Flow Summary

User types  →  ghostid.js collects timings
           →  41 features extracted client-side
           →  POST /score to FastAPI
           →  Feature scaling + ONNX inference
           →  128-dim embedding compared to baseline
           →  Confidence score computed
           →  Tier decision returned
           →  SDK reacts (silent / nudge / challenge / stop)

📁 Project Structure

GhostId/
├── backend/                        # FastAPI inference server
│   ├── app/
│   │   ├── core/                  # Config, security, crypto helpers
│   │   ├── db/                    # SQLite database layer
│   │   ├── models/                # Pydantic request/response schemas
│   │   ├── routes/                # API endpoints: /enroll, /score, /status
│   │   ├── services/              # Business logic (scoring, enrollment)
│   │   └── middleware/            # API key auth, rate limiting
│   ├── ml/                        # ONNX model + scaler_params.json
│   ├── tests/                     # pytest suite (10+ test cases)
│   ├── main.py                    # FastAPI application entry point
│   ├── requirements.txt           # Python dependencies
│   └── .env.example               # Environment variable template
│
├── frontend/                       # React + Vite demo app
│   ├── src/
│   │   ├── components/            # UI components (tiers, nudge, challenge)
│   │   ├── hooks/                 # useKeystroke — live feature capture hook
│   │   └── utils/                 # API client, tier mapping utilities
│   ├── package.json
│   └── vite.config.js
│
├── sdk/                            # Drop-in browser library
│   ├── ghostid.js                 # Main SDK — add to any web app
│   └── features.js                # 41-feature extraction engine
│
├── ml/                             # Model training & evaluation
│   ├── notebooks/
│   │   └── ghostid_training.ipynb      # Full training pipeline
│   ├── models/                    # Saved ONNX + scaler params
│   └── analysis/                  # Benchmark plots, EER curves
│
├── .github/
│   └── workflows/
│       └── ci.yml                 # GitHub Actions: lint, test, build, ONNX validate
│
├── DEPLOYMENT.md                  # Production setup guide (Docker, Railway, Vercel)
├── LICENSE                        # MIT License
└── README.md

🧬 ML Pipeline

GhostID trains an LSTM auto-encoder using ArcFace loss on the CMU DSL Keystroke Dynamics Dataset.

Feature Extraction (41 Features)

Each keystroke window produces 41 features capturing the rhythm of a user's typing:

• Dwell time         — how long each key is held down
• Flight time        — time between key release and next key press
• Latency metrics    — inter-key timing distributions
• Speed-invariant ratios — angle features that normalize for typing speed

Model Architecture

Input (41 features)
       │
       ▼
  ┌─────────────────────────────────────────────────┐
  │           Feature Scaling (saved scaler)        │
  └──────────────────────────┬──────────────────────┘
                             │
                             ▼
  ┌─────────────────────────────────────────────────┐
  │         Bidirectional LSTM Encoder              │
  │   • 2× BiLSTM layers with dropout               │
  │   • Bottleneck: 128-dimensional embedding       │
  │   • L2 normalization on output                  │
  └──────────────────────────┬──────────────────────┘
                             │
                             ▼
  ┌─────────────────────────────────────────────────┐
  │   ArcFace Loss (angular margin m = 0.5)         │
  │   • Pulls same-user embeddings together         │
  │   • Pushes different-user embeddings apart      │
  └─────────────────────────────────────────────────┘
                             │
                             ▼
  128-dim L2-normalized behavioral embedding
  → enables fast cosine similarity at inference time

Training Steps

Step 1 — Download the dataset

# CMU DSL Keystroke Dynamics Dataset
# File: DSL-StrongPasswordData.csv
# Available on Kaggle: search "CMU DSL Keystroke Dynamics"
cd ml/

Step 2 — Run the training notebook

Open the Kaggle Notebook for GhostID v3 Training
Attach dataset: CMU-DSL/DSL-StrongPasswordData.csv
Run all cells (~5 minutes with GPU T4)
Download outputs: ghostid_encoder.onnx and scaler_params.json

Step 3 — Deploy the models

cp ghostid_encoder.onnx ../backend/ml/
cp scaler_params.json   ../backend/ml/

Mock mode: Without these files in backend/ml/, the backend auto-falls back to placeholder scoring — great for frontend development without a trained model.

📊 Benchmark Results

Evaluated on the CMU DSL Keystroke Dynamics Dataset (51 users, 400 sessions/user, 20,400 sessions total):

Metric	Value	What It Means
FAR (False Accept Rate)	2.1%	Impostors accepted as legitimate
FRR (False Reject Rate)	3.8%	Legitimate users incorrectly challenged
EER (Equal Error Rate)	~3.0%	Balanced operating point
Inference Latency	< 1ms	Per scoring query on CPU
Model Size	~60 KB	ONNX format — tiny and deployable
Enrollment Sessions	2	Minimum required to build baseline
Baseline Validity	7 days	Before re-enrollment is recommended

At EER ~3.0%, GhostID is more accurate than many OTP systems while requiring zero user action for the 96%+ of sessions that are legitimate.

🚀 Quick Start

Prerequisites

Python 3.11+ with pip
Node.js 20+ with npm
SQLite (bundled with Python)

1️⃣ Backend Setup

cd backend

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate          # macOS/Linux
# .venv\Scripts\activate           # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env — set API_KEY and EMBEDDING_ENCRYPTION_KEY

# Initialize the database
python -c "from app.db.database import init_db; init_db(); print('✅ DB initialized')"

# Start the API server
python main.py

Backend: http://localhost:8000 · API Docs: http://localhost:8000/docs

2️⃣ Frontend Setup

cd frontend

npm install
cp .env.example .env
# Set VITE_API_URL=http://localhost:8000 and VITE_API_KEY

npm run dev

Frontend: http://localhost:5173

3️⃣ SDK Integration (Drop-in)

Add GhostID to any existing web app in two lines:

<script src="ghostid.js"></script>
<script>
  GhostID.init({
    userId: 'user-123',
    apiUrl: 'https://your-backend.railway.app',
    apiKey: 'your-api-key',
    intervalSeconds: 60,
    onAction: (tier, score) => {
      if (tier === 'HARD_STOP') redirectToLogin();
    }
  });
</script>

4️⃣ Run Tests

cd backend

# Full test suite
pytest tests/test_endpoints.py -v

# With coverage report
pytest tests/test_endpoints.py --cov=app --cov-report=term-missing

Test coverage includes:

✅ Health check endpoint
✅ User enrollment (single & multiple sessions)
✅ Enrollment status retrieval
✅ Profile deletion
✅ Scoring for enrolled and non-enrolled users
✅ Input validation and error handling

🔐 Security

GhostID is built security-first:

Feature	Details
API Key Auth	Bearer token via `X-GhostID-Key` header on every request
Rate Limiting	100 requests/min per user — configurable
Encrypted Embeddings	Fernet symmetric encryption for all stored embeddings
CORS Protection	Configurable allowed origins list
Input Validation	Strict 41-feature vector schema via Pydantic
No Raw Keystrokes Stored	Only statistical feature vectors — GDPR friendly
Secure Defaults	`.env.example` template with guidance on key generation

🚢 Deployment

Docker (Recommended)

# Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env with your keys

# Build and run everything
docker compose up --build

Services start on:

Backend API: http://localhost:8000
Frontend: http://localhost:5173

Production: Backend → Railway

# In Railway dashboard:
# New Project → Deploy from GitHub → Root: backend/
# Start command:
uvicorn main:app --host 0.0.0.0 --port $PORT

# Environment variables to set:
EMBEDDING_ENCRYPTION_KEY=<generated-key>
API_KEY=<your-api-key>
DATABASE_URL=sqlite:///ghostid.db

Production: Frontend → Vercel

# In Vercel dashboard:
# Root: frontend/ | Build: npm run build | Output: dist/

# Environment variables:
VITE_API_URL=https://your-backend.up.railway.app
VITE_API_KEY=your-api-key

Post-Training Deployment Checklist

☐  Run ml/notebooks/ghostid_training.ipynb on Kaggle (GPU ~5 min)
☐  Copy ghostid_encoder.onnx   → backend/ml/
☐  Copy scaler_params.json     → backend/ml/
☐  Copy analysis PNGs          → ml/analysis/
☐  Re-run CI — ONNX validation job should pass
☐  Set production environment variables
☐  Deploy backend to Railway
☐  Deploy frontend to Vercel

❓ FAQ

Q: Does GhostID work on mobile browsers? Yes — the JavaScript SDK captures touch-keyboard keystroke timings. Feature extraction adapts to on-screen keyboards automatically.

Q: What if the ONNX model files aren't present? The backend runs in mock mode with placeholder scoring. This lets frontend developers build and test the UI without a trained model.

Q: Can GhostID detect copy-paste attacks? Yes — copy-pasted input produces zero inter-key flight time, which scores as a significant behavioral anomaly.

Q: Is keystroke data stored in the clear? No. Raw keystrokes are never transmitted. Only the 41-feature statistical vector is sent, and embeddings stored in the database are Fernet-encrypted.

Q: How long does enrollment take? Just 2 typing sessions. The baseline is valid for 7 days by default, after which re-enrollment is recommended to account for natural behavioral drift.

Q: What's the performance impact of running GhostID? Negligible. The JS SDK runs asynchronously, ONNX inference is <1ms CPU, and scoring only fires every 60 seconds.

🎥 Demo

Live demo: ghost-id-rho.vercel.app

🤝 Contributing

Contributions are welcome — bug fixes, new features, documentation, and test coverage.

# 1. Fork the repo and clone your fork
git clone https://github.com/your-username/GhostId.git

# 2. Create a feature branch
git checkout -b feature/my-improvement

# 3. Make your changes and commit
git commit -m "feat: add my improvement"

# 4. Push and open a Pull Request
git push origin feature/my-improvement

All PRs must pass CI (lint, tests, build, ONNX validation) before merging.

📄 License

This project is licensed under the MIT License — see LICENSE for details.

You are free to use, modify, and distribute this project commercially or privately. Just include the license notice.

📞 Support & Docs

📖 Production guide: DEPLOYMENT.md
🐛 Bug reports: GitHub Issues
💬 Questions: GitHub Discussions

GhostID — Your users have a typing fingerprint. GhostID watches it.

Built with ❤️ by Yogesh Rayal

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
backend		backend
frontend		frontend
ml		ml
sdk		sdk
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

👻 GhostID

Continuous Behavioral Session Verification — Zero Friction for Real Users

🧠 What It Does

🎯 Use Cases

🏗️ Architecture

Data Flow Summary

📁 Project Structure

🧬 ML Pipeline

Feature Extraction (41 Features)

Model Architecture

Training Steps

📊 Benchmark Results

🚀 Quick Start

Prerequisites

1️⃣ Backend Setup

2️⃣ Frontend Setup

3️⃣ SDK Integration (Drop-in)

4️⃣ Run Tests

🔐 Security

🚢 Deployment

Docker (Recommended)

Production: Backend → Railway

Production: Frontend → Vercel

Post-Training Deployment Checklist

❓ FAQ

🎥 Demo

🤝 Contributing

📄 License

📞 Support & Docs

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages