README.md

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

# MorphGuard

![MorphGuard Logo](static/img/logo.png)

## Enterprise AI-Powered Facial Morphing Detection & Demorphing Platform

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch 2.6+](https://img.shields.io/badge/PyTorch-2.6%2B-EE4C2C.svg)](https://pytorch.org/)
[![CUDA 12.8](https://img.shields.io/badge/CUDA-12.8-76B900.svg)](https://developer.nvidia.com/cuda-toolkit)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

1. [Overview](#-overview)
2. [Features](#features)
3. [API Usage](#-api-usage)
4. [Quick Start](#quick-start)
5. [Documentation](#documentation)
6. [Architecture](#architecture)
7. [Configuration](#-configuration)
8. [Model Performance](#-model-performance)
9. [Use Cases](#-use-cases)
10. [Contributing](#contributing)

[Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Architecture](#architecture) • [Contributing](#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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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](QUICKSTART.md)** - Get up and running in 5 minutes
- **[Setup Guide](SETUP_GUIDE.md)** - Detailed installation instructions
- **[Web UI Guide](WORKFLOW_GUIDE.md)** - How to use the interface
- **[API Documentation](docs/API.md)** - RESTful API endpoints
- **[Training Guide](docs/TRAINING.md)** - How to train custom models
- **[Deployment Guide](BETA_DEPLOYMENT_GUIDE.md)** - Production deployment
- **[Architecture Overview](docs_archive/COMPREHENSIVE_SYSTEM_ASSESSMENT.md)** - System architecture
- **[Contributing](CONTRIBUTING.md)** - How to contribute

---

## Architecture

```text
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:

```bash
# 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

```bash
# 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](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# 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](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](https://github.com/yourusername/MorphGuard/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/MorphGuard/discussions)
- **Email**: <support@morphguard.ai>

---

### Made with ❤️ by the MorphGuard Team

[Website](https://morphguard.ai) • [Documentation](https://docs.morphguard.ai) • [Blog](https://blog.morphguard.ai)