Spaces:

juanquy
/

MorphGuard

Running

App Files Files Community

MorphGuard / README.md

juanquy

Update README.md

8ddfcee verified about 2 months ago

preview code

Raw

History Blame Contribute Delete

13.2 kB

metadata

title: MorphGuard
emoji: 🛡️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: agpl-3.0

MorphGuard

Enterprise AI-Powered Facial Morphing Detection & Demorphing Platform

Overview
Features
API Usage
Quick Start
Documentation
Architecture
Configuration
Model Performance
Use Cases
Contributing

Features • Quick Start • Documentation • Architecture • Contributing

📋 Overview

MorphGuard is a state-of-the-art AI platform designed to detect, analyze, and reverse facial morphing attacks. It combines multiple deep learning models including Vision Transformers (ViT), GANs, and XceptionNet to provide comprehensive protection against morphing attacks in identity verification systems.

Key Capabilities

🔍 Morph Detection: 95%+ accuracy using Vision Transformer (M2TR) architecture
🎭 Deepfake Detection: 96%+ accuracy using XceptionNet for synthetic face detection
🔄 Demorphing: Dual-mode engine supporting Vision Transformer (Real) and GAN (pSp) for high-fidelity reconstruction.
✅ Identity Verification: Face verification with ArcFace embeddings
🚁 Drone Surveillance: Real-time face detection with Heads-Up Display (HUD), unified telemetry, and Pi 5 + Hailo edge AI.
📊 Real-time Monitoring: Live system metrics via setup dashboard
⛓️ Blockchain Integration: Ethereum-based verification logging
🌐 RESTful API: Production-ready API with comprehensive endpoints
🎯 Adversarial Defense: Robustness against adversarial attacks

Features

Detection Systems

Morph Attack Detection (MAD)
- Vision Transformer (ViT) based M2TR architecture
- Multi-scale feature extraction
- 95%+ accuracy on benchmark datasets
- Real-time inference (<200ms)
Drone Surveillance & Edge AI
- Unified Link: Single WebSocket connection for Video, Telemetry, and Detection alerts.
- Visual HUD: Real-time overlay with Green (Safe) and Red (Threat) bounding boxes.
- Telemetry Relay: Standalone updates for Attitude (Roll/Pitch/Yaw) and GPS.
- Simulation Mode: Full software-in-the-loop testing via simulate_drone.py.
Deepfake Detection
- Integrated XceptionNet architecture (threshold optimized to 0.45)
- Unified pipeline distinguishing "Morphed" vs "AI Generated"
- Analyzes synthetic artifacts and heatmaps
CTM Forensic Agent
- Continuous Thought Machine for deep forensic analysis
- Generates "Reasoning Traces" and Evidence Videos
- Multi-step verification for high-risk morphs
Liveness Detection
- Active liveness verification (Client-side alerts)
- Presentation attack detection (PAD)
- Multi-frame temporal analysis
Identity Search & Forensic Audit
- Reverse Identity Search: 1:N face searching against a local database using facenet-pytorch.
- Advanced Forensic Audit: Cross-reference morphs with potential source identities using CTM attention and regional similarity analysis.
- Automated Reporting: Generates textual audit conclusions linking CTM observations to specific candidate match percentages.

Demorphing & Reconstruction

Smart Demorph Workflow
- Detect-First Architecture: Naturally integrates with unified detection.
- Returns is_morphed status and confidence scores alongside restored image.
Dual-Engine Capabilities
- Transformer Mode: Fast, structure-preserving demorphing using Vision Transformers.
- GAN Mode: High-fidelity reconstruction using pSp (pixel2style2pixel) and StyleGAN2.
- Diffusion Mode: Supported experimentally via Stable Diffusion img2img.
Identity Verification
- ArcFace embeddings (512-d vectors)
- Cosine similarity matching
- Sub-second verification times

Monitoring & Analytics

Real-time Dashboards
- Live system metrics
- GPU/CPU/Memory monitoring
- Detection confidence tracking
- Training progress visualization
TimescaleDB Backend
- Time-series metrics storage
- Efficient querying for large datasets
- Automatic data retention policies

Security & Compliance

Blockchain Verification
- Ethereum smart contract integration
- Immutable audit trail
- Decentralized verification logs
Adversarial Robustness
- Defense against FGSM, PGD, C&W attacks
- Input preprocessing and augmentation
- Ensemble model voting

🔌 API Usage

Unified Detection Endpoint

import requests

# Detect morphed or deepfake image
# detection_type options: 'morph', 'deepfake', 'both'
with open('test_image.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:5000/api/detect',
        files={'file': f},
        data={'detection_type': 'both', 'mode': 'auto'}
    )

result = response.json()
print(f"Verdict: {result['verdict']}")         # 'AUTHENTIC', 'MORPH_DETECTED', or 'AI_GENERATED'
print(f"Confidence: {result['confidence']:.2%}")
print(f"Is Deepfake: {result.get('is_deepfake', False)}")
if 'ctm_analysis' in result:
    print("Forensic Analysis Available")

# Identity Search
# image: The probe image (morph)
# top_k: Number of matches to return
response = requests.post(
    'http://localhost:5000/api/identity/search',
    files={'image': open('morph.jpg', 'rb')},
    data={'top_k': 5}
)
matches = response.json()['matches']

# Advanced Forensic Audit
# image: The probe image
# candidates: Comma-separated filenames of candidates found in search
response = requests.post(
    'http://localhost:5000/api/identity/audit',
    files={'image': open('morph.jpg', 'rb')},
    data={'candidates': 'citizen_a.jpg,citizen_b.jpg'}
)
report = response.json()['report']
print(report['conclusion'])

Quick Start

Prerequisites

Hardware:
- NVIDIA GPU with CUDA Compute Capability ≥ 8.0
- Recommended: RTX 4070 Ti or higher
- 16GB+ RAM, 8GB+ VRAM
Software:
- Ubuntu 20.04+ (or compatible Linux)
- Python 3.10+
- CUDA 12.8+ toolkit
- Conda or Miniconda

Installation

# Clone the repository
git clone https://github.com/yourusername/MorphGuard.git
cd MorphGuard

# Run automated setup (requires sudo)
sudo ./setup_conda_environment.sh

# Activate the environment
conda activate morphguard

# Configure environment variables
cp .env.development.example .env.development
# Edit .env.development with your settings

Starting the Server

# Development mode (with hot reload disabled for GPU efficiency)
./start.sh

# Or run directly with Python
conda activate morphguard
python app.py

The application will be available at:

Main Interface: http://localhost:5000
Demo Page: http://localhost:5000/demo
Setup & Training: http://localhost:5000/setup (Login: admin / morphguard_admin)

Quick Test

# Test detection API
curl -X POST -F "image=@test_image.jpg" http://localhost:5000/api/detect

# Test demorphing (Transformer)
curl -X POST -F "image=@morph.jpg" -F "method=transformer" http://localhost:5000/api/demorph

# Test demorphing (GAN)
curl -X POST -F "image=@morph.jpg" -F "method=gan" http://localhost:5000/api/demorph

Documentation

Quick Start Guide - Get up and running in 5 minutes
Setup Guide - Detailed installation instructions
Web UI Guide - How to use the interface
API Documentation - RESTful API endpoints
Training Guide - How to train custom models
Deployment Guide - Production deployment
Architecture Overview - System architecture
Contributing - How to contribute

Architecture

MorphGuard/
├── src/
│   ├── models/           # AI model architectures
│   │   ├── morph_detector.py      # M2TR Vision Transformer
│   │   ├── demorpher_model.py     # pSp GAN demorpher
│   │   └── identity_verifier.py   # ArcFace verifier
│   ├── deepfake/         # Deepfake detection
│   │   └── deepfake_detector.py   # XceptionNet detector
│   ├── api/              # API endpoints
│   ├── blockchain/       # Ethereum integration
│   └── adversarial/      # Adversarial defense
├── templates/            # Web UI templates
├── static/               # CSS, JS, images
├── scripts/              # Utility scripts
│   ├── train_detector.py
│   ├── train_demorpher.py
│   └── evaluate_model.py
├── models/               # Trained model weights
├── data/                 # Training/validation data
│   ├── train/
│   │   ├── morph/
│   │   └── real/
│   └── val/
└── app.py               # Main Flask application

Technology Stack

Component	Technology
Backend	Python 3.10, Flask, Flask-SocketIO
AI/ML	PyTorch 2.6+, timm, torchvision
Database	PostgreSQL 15 + TimescaleDB
Blockchain	Ethereum (Web3.py)
Frontend	HTML5, TailwindCSS, Chart.js
Real-time	Socket.IO, WebSockets

🔧 Configuration

Environment Variables

Create a .env.development file:

# Flask Configuration
FLASK_ENV=development
FLASK_DEBUG=True
MORPHGUARD_SECRET_KEY=your-secret-key-here

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=morphguard
DB_USER=morphguard
DB_PASSWORD=morphguard

# GPU Configuration
CUDA_VISIBLE_DEVICES=0
TORCH_CUDA_ARCH_LIST=8.9;9.0

# Model Paths
DETECTOR_MODEL_PATH=models/morph_detector.pth
DEMORPHER_MODEL_PATH=models/demorpher.pth
VERIFIER_MODEL_PATH=models/identity_verifier.pth


# Blockchain (optional)
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR-PROJECT-ID
ETHEREUM_CONTRACT_ADDRESS=0x...

📊 Model Performance

Model	Dataset	Accuracy	Precision	Recall	F1-Score	Inference Time
M2TR Detector	FRLL-Morphs	95.2%	94.8%	95.6%	95.2%	145ms
XceptionNet	FaceForensics++	96.4%	96.1%	96.7%	96.4%	162ms
pSp Demorpher	Custom	87.3%	-	-	-	890ms
ArcFace Verifier	LFW	99.8%	99.7%	99.9%	99.8%	23ms

Tested on NVIDIA RTX 5070 with CUDA 12.8

🛠️ Training Custom Models

# Train morph detector
python scripts/train_detector.py \
  --data-dir data \
  --epochs 50 \
  --batch-size 32 \
  --lr 0.0001 \
  --model-name vit_base_patch16_224

# Train demorpher
python scripts/train_demorpher.py \
  --data-dir data \
  --epochs 100 \
  --batch-size 16

# Evaluate model
python scripts/evaluate_model.py \
  --model-path models/morph_detector.pth \
  --test-dir data/test

🎯 Use Cases

Border Control & Immigration: Detect morphed passport photos
Identity Verification: Secure KYC processes
Financial Services: Prevent identity fraud
Healthcare: Protect patient identity systems
Government Services: Secure ID issuance
Social Media: Deepfake content moderation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Code formatting
black src/ scripts/
flake8 src/ scripts/

# Type checking
mypy src/

📝 License

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

🙏 Acknowledgments

M2TR Architecture: Based on "Morphing Detection Transformers" research
pSp Encoder: From "Encoding in Style: a StyleGAN Encoder for Image-to-Image Translation"
XceptionNet: Based on "Xception: Deep Learning with Depthwise Separable Convolutions"
ArcFace: Based on "ArcFace: Additive Angular Margin Loss for Deep Face Recognition"

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@morphguard.ai

Made with ❤️ by the MorphGuard Team

Website • Documentation • Blog