Sentinel Face Secure is a facial authentication and security monitoring platform. It implements real-time webcam face verification with anti-spoofing algorithms, a highly responsive React (Vite) frontend dashboard, and an AI-powered agent (via Groq API) for SOC analysis and log threat evaluation.
- Real-Time Facial Auth: Detects faces using OpenCV and verifies identity using CNN embeddings and cosine similarity.
- Liveness Detection: Employs eye aspect ratio (EAR) and depth analysis to mitigate spoofing attempts via photos or screens.
- Secure Dashboard: Granular access control with separate views for Admins, Managers, and Employees.
- AI Security Analyst (Groq): Analyzes logs in real-time, generates SOC briefings, and evaluates threats. Note: AI features require your own Groq API Key to be configured in the Security Settings tab on the dashboard.
- Live Event Stream: Real-time logging of access attempts across environments.
- Python 3.10+
- Node.js 18+
- MongoDB instance (local or Atlas)
cd server
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.pyThe backend will run on http://localhost:5001.
cd client
npm install
npm run devThe frontend will run on http://localhost:5173.
The application is architected for decoupled cloud deployment.
Ensure you have committed your changes and pushed to your GitHub repository securely, ensuring no sensitive files (e.g., .env, .encryption_key) are tracked:
git add .
git commit -m "chore: prepare for production deployment"
git push origin mainThe backend API is containerized and configured for Hugging Face Spaces (Docker environment).
- Create a new Space on Hugging Face using the Docker template.
- In your Space's Settings > Variables and secrets, add
MONGODB_URIpointing to your MongoDB Atlas connection string. - Push the contents of the
serverdirectory (including theDockerfile) to the Space. - The Space will automatically build and expose the FastAPI application.
The React dashboard can be deployed directly from the GitHub repository using Vercel.
- Connect your GitHub repository to Vercel.
- Ensure the Root Directory is left empty (or set to
./), as thepackage.jsonis located in the repository root. - Add a new Environment Variable
VITE_API_URLand set its value to your deployed Hugging Face Space URL. - Deploy the application.
The application securely handles AI API keys on the client-side. Users input their X-Groq-Api-Key into the Dashboard's settings modal, which is passed securely via headers to the backend for AI evaluation.
Disclaimer: This project is built for educational and advanced security demonstration purposes.
The platform operates on a decoupled client-server architecture:
- Frontend (React/TypeScript): Handles user interaction, camera stream acquisition, and frame optimization before transmission.
- API Gateway (FastAPI): Validates requests and routes payloads to respective microservices for detection, liveness evaluation, and feature extraction.
- Computer Vision Engine:
- Detection: Utilizes Haar Cascades or YOLO-Nano for face localization.
- Feature Extraction: Generates 128-dimensional embeddings using a customized MobileNetV2 architecture pretrained on ImageNet.
- Liveness Evaluation: Evaluates temporal frame sequences for biological viability.
- Security Operations Center: Integrates large language models (LLMs) via the Model Context Protocol (MCP) to autonomously evaluate authentication logs, assign risk scores, and generate security reports.
- Database Layer (MongoDB): Stores encrypted vector embeddings and immutable audit logs.
- Architecture: MobileNetV2 with a custom dense embedding layer (
Dropout -> Linear -> BatchNorm1d). - Embedding Dimensions: 128 (L2 Normalized).
- Distance Metric: Cosine Similarity.
- Privacy: Raw images are not persisted. Only mathematical vector embeddings are stored.
- Storage Security: Embeddings are encrypted at rest using AES-128 (Fernet).
The system employs a weighted probabilistic model to mitigate presentation attacks:
- Active Liveness: Eye Aspect Ratio (EAR) monitoring for blink detection.
- Passive Liveness: Frame-to-frame pixel intensity difference for static media detection.
- Spatial Variance: Bounding box scale monitoring to track 3D head movement.
- Artifact Analysis: Laplacian variance and FFT analysis to detect screen refresh rates and compression artifacts inherent in replay attacks.
- Autonomous Monitoring: Background daemon analyzing log streams for anomalous authentication patterns.
- Risk Scoring Engine: Algorithmic calculation of threat levels based on biometric confidence, liveness thresholds, and temporal login frequency.
- Evaluation Pipeline: MLOps framework testing the SOC agent against a ground-truth dataset of simulated intrusion attempts to benchmark false positive rates and analytical latency.
- Reporting Engine: Automated generation of PDF security compliance reports.
sentinel-face-secure/
├── client/ # Frontend Application
│ ├── src/ # Source code (Components, Hooks, Pages)
│ ├── package.json # Node dependencies
│ └── vite.config.ts # Vite build configuration
│
├── server/ # Backend API and AI Services
│ ├── main.py # FastAPI application entry point
│ ├── cnn_embedding.py # CNN architecture definition
│ ├── liveness_detection.py # Liveness evaluation algorithms
│ ├── autonomous_agent.py # Background SOC monitoring daemon
│ ├── mcp_server.py # Model Context Protocol integration
│ ├── database.py # Asynchronous MongoDB client
│ ├── encryption.py # Cryptographic utilities
│ ├── evals/ # MLOps evaluation dataset and runners
│ └── requirements.txt # Python dependencies
│
└── docs/ # Technical documentation and reviews- Node.js (v18 or higher)
- Python (3.9 or higher)
- MongoDB (v5.0 or higher)
Create a .env file in the server directory:
PORT=5001
MONGODB_URI=mongodb://localhost:27017
DB_NAME=sentinel_face
ENCRYPT_EMBEDDINGS=true
USE_YOLO=false
GROQ_API_KEY=your_api_key_herecd server
pip install -r requirements.txt
python main.pycd client
npm install
npm run devMIT License