BioLock-Exam

Continuous Biometric Keystroke Dynamics Anomaly Detector for Remote Online Examinations

BioLock-Exam detects identity fraud and ghostwriting in remote exams by continuously measuring a student's keystroke dynamics — the unique timing of their typing — instead of invasive, bandwidth-heavy webcam surveillance. It trains a personal one-class machine-learning baseline per student, then flags any window of typing that deviates behaviorally from that baseline in real time.

Student Key Events (Raw Stream) ──► [Rolling Circular Buffer]
                                          │
                                          ▼
                         [Feature Extractor: Flight & Dwell Times]
                                          │
                                          ▼
                 [ML Anomaly Detector: Isolation Forest / OC-SVM / Z-score]
                                          │
                                          ▼
                 [SQLAlchemy Audit Log & Observer-Pattern Risk Alerts]
                                          │
                                          ▼
                    [Webhook dispatch to LMS + Proctor Dashboard]

---

Features

• OOP Architecture — BaseAnomalyDetector with polymorphic StatisticalZScoreDetector, IsolationForestDetector, OneClassSVMDetector, and EnsembleBiometricDetector.
• Observer Pattern — WebhookDispatcher (an AlertSubject) notifies proctors & LMS endpoints when risk crosses thresholds.
• Advanced Data Structures — O(1) thread-safe CircularRingBuffer, KDTree for fast k-NN search of baseline profiles, and a DigraphTransitionMatrix for key-pair latency modeling.
• Concurrency / Parallelism — threading background telemetry worker, asyncio WebSocket-style telemetry stream, and multiprocessing cohort evaluator.
• Database & External APIs — SQLAlchemy + SQLite audit logs & baseline profiles; webhook dispatch to external LMS platforms (stdlib only).
• Machine Learning — scikit-learn OneClassSVM, IsolationForest, Z-score/Mahalanobis, and a weighted ensemble.
• Privacy / FERPA-GDPR — PrivacyAnonymizer hashes character keys so no raw essay text is ever stored.
• Professional TUI — Rich-based exam-room dashboard and proctor oversight view with educational themes.
• Educational Content — an interactive "campus security tour" mapping each subsystem to a security lesson.

---

Installation

Requires Python 3.12+ and uv.

uv sync                 # install all dependencies
uv run python src/main.py --help   # confirm the CLI works

---

Quick Start (2 minutes)

# 1. Initialize the audit database + seed a demo cohort
make setup

# 2. Launch a deterministic demo exam session (no keyboard needed)
make demo

# 3. Run the proctor dashboard
make proctor

# 4. Benchmark detectors against spoofing/impersonation attacks
make simulate

---

CLI Reference

Command	Description
setup	Initialize DB and seed demo students/exams.
calibrate <student-id>	Train a student's biometric baseline profile.
exam <student-id> [--demo] [--theme <key>]	Launch the live exam-room TUI. --demo runs a deterministic session.
monitor	Async real-time proctor risk stream.
proctor	Cohort security-oversight dashboard.
simulate	Benchmark a detector against spoofed/impersonator sessions.
campus	Interactive educational security tour.
themes	Preview educational interface themes.
report	Human-readable integrity audit report.
version	Print version.

Examples

# Live exam room with a keyboard, cyber theme, and an LMS webhook
uv run python src/main.py exam S1001 --name "Ada Lovelace" --theme cyber_shield \
    --webhook https://lms.example.edu/hook

# Calibrate a new student baseline
uv run python src/main.py calibrate S2040 --profile deliberate --detector statistical

# Run the async proctor monitor
uv run python src/main.py monitor --student S1001 --duration 20

---

Educational Themes

Switch the look of the exam room, dashboards, and tour via --theme <key>:

• oxford_blue — Oxford Academic Blue (default)
• cyber_shield — Cyber Defense Shield
• emerald_campus — Emerald Campus Quad
• crimson_ivy — Crimson Ivy League
• monochrome — Monochrome Terminal

Run make themes to preview them.

---

Testing

The suite validates the two core security guarantees — synthetic typing-pattern spoofing detection and drift compensation — plus structures, features, detectors, concurrency, storage, and webhooks.

make test          # or: uv run python -m pytest -q

Coverage highlights (tests/):

• test_attack_vectors.py — ghostwriter takeover, bot injection, paste burst, and drift re-calibration.
• test_detectors.py — every detector trains, predicts, serializes, and separates authentic vs. impersonator typing.
• test_structures.py — ring buffer, k-d tree, and digraph matrix.
• test_concurrency.py — background worker thread + async telemetry stream.
• test_storage_and_webhooks.py — SQLAlchemy repository flow + live local webhook delivery.
• test_services_integration.py — calibration, benchmark, demo seeding, proctor view.

---

Project Layout

src/main.py                     # Typer CLI entry point
src/biolock/
  config.py                     # settings, risk thresholds, theme palettes
  education.py                  # campus tour + educational content
  services.py                   # high-level orchestration (calibrate/exam/proctor simulation)
  structures/                   # ring buffer, k-d tree, digraph matrix
  features/                     # extractor, models, privacy anonymizer
  detectors/                    # base, statistical, isolation forest, OC-SVM, ensemble, factory/observer
  concurrency/                  # background worker, async telemetry stream, batch evaluator
  storage/                      # SQLAlchemy models, database, repository
  simulation/                   # synthetic data + attack vectors
  integrations/                 # webhook dispatcher → LMS
  ui/                           # Rich TUI (themes, exam room, proctor dashboard)
tests/                          # pytest suite
conftest.py                     # makes src importable; in-memory DB fixture

---

Architecture Notes

Why one-class models? BioLock never labels "attacker" data. It fits the student's own typing baseline and flags anything statistically unlike it — so previously-unseen ghostwriters, bots, and paste bursts are still caught.

Why a ring buffer? Keystrokes arrive at human speed (tens of ms); a fixed-capacity circular buffer gives O(1) append/overwrite for the sliding window with no allocation churn under concurrent capture.

Why a k-d tree? Nearest-neighbor distance to a stored baseline is the natural "how normal is this" query. Branched search keeps it O(log n) so inference stays real-time across a semester cohort.

Why observer pattern + webhooks? Decoupling detection from notification means adding a Moodle, Canvas, Teams, or Slack sink never touches the detection code; alert delivery is non-blocking via a thread pool.

---

License

Distributed under the MIT License.

Educational demonstrator for the Advanced Python Programming (ICT-6111) examination project.