synth-guard - GitLite

KO | EN

gitlite — search

#codex #terminal #proxy #cpp #postgresql #markdown #open-source #chatbot #json #android

synth-guard

(★ 9)

High-performance multimedia OSINT engine. Detects AI deepfakes and synthetic media using biological (rPPG), structural (DCT), and spectral forensics

File Explorer

ZIP Download

- - comprehensive-audit.yml
  - python-backend.yml
  - release.yml
- - __init__.py
  - forensics.py
  - processor.py
- - test_math_heuristics.py
- __init__.py
- main.py
- requirements.txt
- - .gitkeep
- - favicon.svg
  - icons.svg
- - App.css
  - App.jsx
  - index.css
  - main.jsx
- .gitignore
- eslint.config.js
- index.html
- package-lock.json
- package.json
- README.md
- vite.config.js
.env.example
.gitignore
docker-compose.yml
Dockerfile
generate_audio_test.py
generate_test.py
LICENSE
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Python
React
FastAPI
Computer Vision
Docker
License: MIT

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

---

[![SYNTH-GUARD Master Audit](https://github.com/GiTaDi-CrEaTe/synth-guard/actions/workflows/comprehensive-audit.yml/badge.svg?branch=main)](https://github.com/GiTaDi-CrEaTe/synth-guard/actions/workflows/comprehensive-audit.yml)
[![SYNTH-GUARD Backend](https://github.com/GiTaDi-CrEaTe/synth-guard/actions/workflows/python-backend.yml/badge.svg?branch=main)](https://github.com/GiTaDi-CrEaTe/synth-guard/actions/workflows/python-backend.yml)

**SYNTH-GUARD** is an enterprise-grade multimedia forensic engine designed to detect synthetic media, AI-generated deepfakes, and voice clones. Rejecting heuristic visual checks, it targets the underlying mathematical, physical, and biological inconsistencies left behind by generative networks (GANs, Diffusion models, Neural Vocoders) across video and audio containers.

---

## ⚙️ Forensic Modalities & Mathematical Bases

The forensic pipeline computes a deterministic aggregate risk score across five independent signal domains:

1. **Biological Coherence (rPPG):** Extracts temporal Green-channel fluctuations across facial skin regions, applies a cardiac bandpass filter (0.75 Hz – 3.5 Hz / 45–210 BPM), and evaluates cardiac Power Spectral Density (PSD) Peak-to-Noise Ratio (PNR) and spectral entropy. Authentic human faces exhibit prominent blood volume pulse periodicities, while deepfakes lack this physiological coherence.
2. **Structural Artifacts (2D-DCT):** Evaluates full-resolution 2D Discrete Cosine Transforms without destructive downsampling to detect periodic high-frequency checkerboard grid artifacts left behind by transposed convolution upsampling in generative networks.
3. **Spectral Forensics (Librosa):** Computes Wiener spectral flatness, spectral centroid dynamics, and MFCC temporal variance on extracted audio to detect neural vocoders, phase discontinuities, and synthetic voice cloning signatures.
4. **Temporal Continuity:** Measures inter-frame structural dissimilarity and facial boundary flickering across sequential frames to detect frame-by-frame generative synthesis seams.
5. **Container & Metadata Provenance (Hachoir):** Scrapes container tags and stream properties for signatures of known generative tools (DeepFaceLab, FaceSwap, Roop, ReActor, ComfyUI, etc.).

---

## 🚀 Performance Benchmarks (Edge & Server Inference)

| Component | Target Artifact | Average Latency | Complexity |
| :--- | :--- | :--- | :--- |
| **rPPG Engine** | Cardiac Pulse Periodicity | ~35ms / frame | $O(N)$ pixel sampling + FFT |
| **DCT Matrix** | Spatial High-Frequency Residuals | ~10ms / frame | $O(N \log N)$ 2D-DCT |
| **Spectral** | Vocoder Phase Flatness & MFCC | ~65ms / clip | Short-Time Fourier Transform |
| **Temporal** | Inter-frame Jitter / Seams | ~8ms / frame | Frame dissimilarity matrix |
| **Metadata** | Container Provenance & Tags | ~5ms / file | Hachoir parser stream check |

*Inference tests conducted on standard x86 CPU architectures without dedicated GPU acceleration, demonstrating lightweight edge-viability.*

---

## 💻 Architecture & Tech Stack

* **Signal Processing & Math:** `NumPy`, `SciPy`, `OpenCV`, `Librosa`, `SoundFile`, `ImageIO-FFmpeg`, `Hachoir`
* **API Framework:** `FastAPI`, `Uvicorn`, `Pydantic`
* **Frontend Visualization:** `React 19`, `Vite 8`, `Tailwind CSS`, `Recharts`, `Framer Motion`, `Lucide React`
* **Quality Assurance:** `pytest`, `Ruff`, `MyPy`, `Bandit`, `ESLint`
* **Containerization:** Multi-stage `Dockerfile`, `docker-compose.yml`

---

## 🐳 Quick Start with Docker (Production Ready)

Run the full production stack with a single command:

```bash
docker compose up --build
```

The unified dashboard and forensic API will be available at `http://localhost:8000`.

---

## 🛠️ Local Development & Deployment

### 1. Backend Setup (FastAPI)
Python 3.13+ is required.

```bash
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py
```

### 2. Frontend Setup (React + Tailwind CSS)
Node.js 20+ is required.

```bash
cd frontend
npm install
npm run dev
```
Access the development UI at `http://localhost:5173`.

### 3. Generate Forensic Test Payloads
Generate simulated synthetic payloads to test detection capabilities:

```bash
python generate_test.py          # Generates test_target.mp4 (2D-DCT grid artifact)
python generate_audio_test.py    # Generates audio_test.mp4 (Vocoder phase flatness)
```

---

## 🧪 Comprehensive Verification Suite

Run all static analysis, security audits, and mathematical unit tests:

```bash
# 1. Rust-based Linter
ruff check .

# 2. Strict Type Checking
mypy backend/ --ignore-missing-imports

# 3. Security Vulnerability Scan
bandit -r backend/ -ll -ii

# 4. Mathematical Forensic Unit Tests
pytest

# 5. Frontend Lint & Production Bundle Build
cd frontend
npm run lint
npm run build
```

---

## 📡 API Reference

### Health Check
```http
GET /health
```
```json
{
  "status": "healthy",
  "service": "synth-guard-api",
  "version": "1.0.0",
  "engine_ready": true,
  "max_upload_size_mb": 100,
  "supported_formats": [".avi", ".mkv", ".mov", ".mp4", ".webm"]
}
```

### Forensic Analysis
```http
POST /analyze
Content-Type: multipart/form-data
Body: file=@video.mp4
```

---

## 📜 License
Distributed under the MIT License. ISO/IEC 27037 Digital Forensics Protocol Compliant.