{"id":46032566,"url":"https://github.com/priyankagnana/deepshield","last_synced_at":"2026-03-07T10:01:16.381Z","repository":{"id":341196464,"uuid":"1169266436","full_name":"priyankagnana/DeepShield","owner":"priyankagnana","description":"DeepShield is a real-time deepfake face detection system built using EfficientNet-B0 and transfer learning, achieving 92% F1-score on 140K face dataset.","archived":false,"fork":false,"pushed_at":"2026-03-03T18:24:50.000Z","size":938,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T10:23:47.471Z","etag":null,"topics":["artificial-intelligence","binary-classification","cnn","computer-vision","cybersecurity","deepfake-detection","efficientnet-b0","face-classification","image-classification","machine-learning","pytorch","transfer-learning"],"latest_commit_sha":null,"homepage":"https://deepshield-ctjjsxczkzzsqfoftct3ra.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/priyankagnana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T12:28:28.000Z","updated_at":"2026-03-03T18:24:54.000Z","dependencies_parsed_at":"2026-03-04T07:02:26.988Z","dependency_job_id":null,"html_url":"https://github.com/priyankagnana/DeepShield","commit_stats":null,"previous_names":["priyankagnana/deepshield"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/priyankagnana/DeepShield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/priyankagnana%2FDeepShield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/priyankagnana%2FDeepShield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/priyankagnana%2FDeepShield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/priyankagnana%2FDeepShield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/priyankagnana","download_url":"https://codeload.github.com/priyankagnana/DeepShield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/priyankagnana%2FDeepShield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30115662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","binary-classification","cnn","computer-vision","cybersecurity","deepfake-detection","efficientnet-b0","face-classification","image-classification","machine-learning","pytorch","transfer-learning"],"created_at":"2026-03-01T04:11:15.132Z","updated_at":"2026-03-05T08:00:50.381Z","avatar_url":"https://github.com/priyankagnana.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ DeepShield — Real-Time Deepfake Detection System\n\nA fully offline, explainable deepfake detection system built on **EfficientNet-B0** with Grad-CAM visual explanations, a polished Streamlit UI, and a FastAPI backend for real-time inference.\n\n---\n\n## 📌 Overview\n\nDeepfake technology uses generative AI to create highly realistic synthetic faces in images and videos. While powerful, it poses serious risks — misinformation, identity fraud, impersonation, and reputational harm.\n\n**DeepShield** addresses this with a privacy-first, fully offline detection pipeline that:\n\n- Classifies images and videos as ✅ **Real** or 🚨 **Fake**\n- Provides **confidence scores** and **P(Real) / P(Fake)** probabilities\n- Explains decisions visually using **Grad-CAM heatmaps**\n- Runs entirely on your machine — **no cloud calls, no data leaves your device**\n\n---\n\n## 🏗️ System Architecture\n\n```\n┌─────────────────────┐\n│   Input (Image /    │\n│   Video / Webcam)   │\n└──────────┬──────────┘\n           ↓\n┌─────────────────────┐\n│   Face Detection    │  ← OpenCV Haar Cascade (face_detector.py)\n│   \u0026 Frame Sampling  │  ← Frame extractor (frame_extractor.py)\n└──────────┬──────────┘\n           ↓\n┌─────────────────────┐\n│  Image Preprocessing│  ← Resize 224×224, ImageNet normalize\n└──────────┬──────────┘\n           ↓\n┌──────────────────────────────────────┐\n│         DeepfakeCNN Model            │\n│                                      │\n│  EfficientNet-B0 (Spatial Branch)    │  → 1280-dim features\n│  +                                   │\n│  FrequencyBranch (FFT Spectrum)      │  → 128-dim features  [opt-in]\n│                                      │\n│  Fused → Linear head → Binary logit  │\n└──────────┬───────────────────────────┘\n           ↓\n┌─────────────────────┐\n│  Classification     │  Real / Fake + confidence score\n└──────────┬──────────┘\n           ↓\n┌─────────────────────┐\n│  Grad-CAM Module    │  Visual heatmap over suspicious regions\n└─────────────────────┘\n```\n\n---\n\n## ✨ Key Features\n\n| Feature | Details |\n|---|---|\n| **EfficientNet-B0 backbone** | ImageNet-pretrained, two-phase fine-tuning |\n| **Frequency-domain analysis** | Optional FFT branch detects GAN grid artefacts |\n| **Face detection** | OpenCV Haar cascade — crops to face before inference |\n| **Grad-CAM explanations** | Heatmap overlay showing which regions drove the decision |\n| **Full video analysis** | Samples N frames evenly, aggregates with majority vote + timeline chart |\n| **Live webcam** | `streamlit-webrtc` in the UI + CLI realtime script |\n| **FastAPI backend** | REST + WebSocket endpoints for image, video, and frame streaming |\n| **Fully offline** | No internet connection required for inference |\n| **MPS / CUDA / CPU** | Auto-detects Apple Silicon, NVIDIA GPU, or CPU |\n\n---\n\n## 📂 Project Structure\n\n```\nDeepShield/\n│\n├── api/                        ← FastAPI backend\n│   ├── main.py                 ← App entry point, model loaded at startup\n│   ├── schemas.py              ← Pydantic response models\n│   └── routes/\n│       ├── predict.py          ← POST /predict/image, POST /predict/video\n│       └── stream.py           ← WS /ws/webcam (real-time frame inference)\n│\n├── model/\n│   ├── cnn_model.py            ← DeepfakeCNN (EfficientNet-B0 + optional FrequencyBranch)\n│   ├── frequency_branch.py     ← FFT-based spectral feature extractor\n│   └── loss.py\n│\n├── inference/\n│   ├── predict.py              ← load_model, predict, predict_image, predict_video, predict_with_gradcam\n│   └── realtime_inference.py   ← CLI webcam / video loop with frame skipping\n│\n├── training/\n│   ├── train.py                ← Two-phase EfficientNet fine-tuning\n│   ├── evaluate.py             ← Test-set evaluation with tqdm progress\n│   ├── dataset.py              ← DataLoader, balanced subset sampling\n│   ├── metrics.py              ← Accuracy, precision, recall, F1, confusion matrix\n│   └── early_stopping.py\n│\n├── preprocessing/\n│   ├── face_detector.py        ← detect_and_crop_face() using OpenCV Haar cascade\n│   ├── frame_extractor.py      ← Extract 30 frames/video with multiprocessing\n│   ├── dataset_split.py        ← Sort raw videos → real/ fake/ using metadata.json\n│   ├── split_train_val_test.py ← 70/15/15 split grouped by video ID\n│   └── augmentations.py\n│\n├── explainability/\n│   ├── gradcam.py              ← Grad-CAM with forward + backward hooks\n│   └── heatmap_utils.py        ← Heatmap colormap overlay\n│\n├── saved_models/\n│   └── best_model.pth          ← Best checkpoint saved during training\n│\n├── app.py                      ← Streamlit UI (Image / Video / Webcam tabs)\n├── requirements.txt\n└── README.md\n```\n\n---\n\n## 🛠️ Tech Stack\n\n| Category | Tools |\n|---|---|\n| **Deep Learning** | PyTorch, TorchVision |\n| **Model** | EfficientNet-B0 (ImageNet pretrained) |\n| **Computer Vision** | OpenCV |\n| **Frequency Analysis** | PyTorch FFT (`torch.fft.fft2`, fftshift) |\n| **Explainability** | Grad-CAM (backward hooks) |\n| **Frontend** | Streamlit, streamlit-webrtc, Plotly |\n| **Backend API** | FastAPI, Uvicorn, WebSockets |\n| **Data / Metrics** | NumPy, Pandas, Scikit-learn |\n| **Training utilities** | tqdm, early stopping |\n\n---\n\n## 📊 Model Performance\n\nTrained on the **140k Real vs Fake Faces** dataset (Kaggle):\n\n| Metric | Score |\n|---|---|\n| Accuracy | ~91–92% |\n| Precision | — |\n| Recall | — |\n| F1 Score | — |\n\n\u003e Run `python -m training.evaluate` after training to get exact numbers on your test split.\n\n---\n\n## 📥 Dataset Setup\n\nThis project uses the **140k Real vs Fake Faces** dataset from Kaggle.\n\n**Download link:** [https://www.kaggle.com/datasets/xhlulu/140k-real-and-fake-faces](https://www.kaggle.com/datasets/xhlulu/140k-real-and-fake-faces)\n\nAfter downloading, place it at the project root:\n\n```\nDeepShield/\n└── 140k-faces/\n    └── real_vs_fake/\n        └── real-vs-fake/\n            ├── train/\n            │   ├── real/\n            │   └── fake/\n            ├── valid/\n            │   ├── real/\n            │   └── fake/\n            └── test/\n                ├── real/\n                └── fake/\n```\n\n\u003e The `140k-faces/` folder is in `.gitignore` and must be placed manually on each machine.\n\n---\n\n## 🚀 Full Setup \u0026 Workflow\n\n### Prerequisites\n\n#### 1. System libraries (macOS — install before creating the venv)\n\n```bash\nbrew install xz cmake libomp\n```\n\n#### 2. Python version (3.10+ recommended)\n\n```bash\npyenv install 3.12.2\npyenv local 3.12.2\n```\n\n#### 3. Virtual environment\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate       # macOS / Linux\n# venv\\Scripts\\activate        # Windows\n```\n\n#### 4. Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n### Step 1 — Train the Model\n\n```bash\npython -m training.train\n```\n\nTrains DeepfakeCNN using two-phase EfficientNet fine-tuning for up to 50 epochs. Best checkpoint is saved to `saved_models/best_model.pth` whenever validation accuracy improves.\n\n**Training phases:**\n- **Phase 1** (epochs 1–5): Backbone frozen, only the classifier head trains at lr=1e-4\n- **Phase 2** (epoch 6+): Last two EfficientNet blocks unfrozen, full model trains at lr=1e-5\n\nSample output:\n```\nEpoch 1/50 [Ph1]  train_loss=0.512  val_loss=0.431  val_acc=0.8120\n...\nEpoch 20/50 [Ph2]  train_loss=0.214  val_loss=0.198  val_acc=0.9167\n```\n\n---\n\n### Step 2 — Evaluate on the Test Set\n\n```bash\npython -m training.evaluate\n```\n\nLoads `saved_models/best_model.pth` and reports Accuracy, Precision, Recall, F1, and Confusion Matrix on the held-out test set. Includes a tqdm progress bar.\n\nSample output:\n```\nEvaluating: 100%|████████████| 625/625 [05:23\u003c00:00]\n\nTest set evaluation\n----------------------------------------\nAccuracy:  0.9167\nPrecision: 0.9210\nRecall:    0.9140\nF1:        0.9175\n```\n\n---\n\n### Step 3 — Launch the Streamlit App\n\n```bash\nstreamlit run app.py\n```\n\nOpens the full UI at `http://localhost:8501`. Three tabs:\n\n#### 📷 Image Tab\n- Upload any face image (JPG/PNG)\n- Shows verdict card with confidence %, P(Real), P(Fake)\n- Enable **Grad-CAM** in sidebar to see which facial regions influenced the decision\n- Plotly donut chart shows Real/Fake probability split\n\n#### 🎬 Video Tab\n- Upload a video (MP4/AVI/MOV)\n- Choose how many frames to analyze (4–32)\n- Summary metrics: frames analyzed, avg P(Real), real/fake frame counts\n- Interactive **P(Real) timeline chart** (per-frame line chart with 0.5 threshold)\n- **Frame distribution histogram** showing score spread\n- Collapsible per-frame detail table\n\n#### 📹 Webcam Tab\n- Live webcam feed via `streamlit-webrtc`\n- Inference every 3rd frame to keep stream smooth\n- Bottom banner shows Real/Fake label + confidence\n- Top bar shows P(Real) as a fill indicator\n- Falls back gracefully if `streamlit-webrtc` is not installed\n\n**Sidebar options:**\n- Toggle Grad-CAM overlay\n- Score interpretation table (what P(Real) ranges mean)\n\n---\n\n### Step 4 — Run the FastAPI Backend\n\n```bash\nuvicorn api.main:app --reload --host 0.0.0.0 --port 8000\n```\n\nModel is loaded **once at startup** and reused for all requests.\n\nInteractive API docs: `http://localhost:8000/docs`\n\n| Endpoint | Method | Description |\n|---|---|---|\n| `/health` | GET | Check if model is loaded and which device is in use |\n| `/predict/image` | POST | Upload image → `{label, confidence, prob_real}` |\n| `/predict/video` | POST | Upload video → aggregated + per-frame results |\n| `/ws/webcam` | WebSocket | Send JPEG bytes → receive JSON predictions in real-time |\n\nExample request (image):\n```bash\ncurl -X POST http://localhost:8000/predict/image \\\n  -F \"file=@face.jpg\"\n```\n\nExample response:\n```json\n{\n  \"label\": \"Fake\",\n  \"confidence\": 0.9312,\n  \"prob_real\": 0.0688\n}\n```\n\n---\n\n### Step 5 — CLI Real-Time Inference (Webcam or Video)\n\n```bash\n# Webcam\npython -m inference.realtime_inference\n\n# Video file\npython -m inference.realtime_inference --video path/to/video.mp4\n\n# With Grad-CAM overlay\npython -m inference.realtime_inference --video path/to/video.mp4 --gradcam\n```\n\nPress **Q** to quit. Inference runs every 3rd frame for smooth display.\n\n---\n\n### Quick Reference\n\n```bash\n# ── Environment ─────────────────────────────────────────\npython3 -m venv venv \u0026\u0026 source venv/bin/activate\npip install -r requirements.txt\n\n# ── Train ───────────────────────────────────────────────\npython -m training.train\n\n# ── Evaluate ────────────────────────────────────────────\npython -m training.evaluate\n\n# ── Streamlit UI ────────────────────────────────────────\nstreamlit run app.py\n\n# ── FastAPI backend ─────────────────────────────────────\nuvicorn api.main:app --reload --port 8000\n\n# ── CLI webcam / video ───────────────────────────────────\npython -m inference.realtime_inference [--video \u003cpath\u003e] [--gradcam]\n```\n\n---\n\n## 🔬 Model Architecture Details\n\n### DeepfakeCNN\n\n```\nEfficientNet-B0 (pretrained on ImageNet)\n  └── features[0..8]  (MBConv blocks)\n  └── classifier\n        ├── Dropout(0.4)\n        └── Linear(1280 → 1)          # Default mode\n\nOptional: use_frequency=True\n  EfficientNet features (1280-dim)\n  + FrequencyBranch (128-dim)\n  → Linear(1408 → 256) → ReLU → Dropout(0.4) → Linear(256 → 1)\n```\n\n### FrequencyBranch\n\nDetects spectral artefacts characteristic of GAN-generated images:\n\n1. `torch.fft.fft2` — 2D Fast Fourier Transform\n2. `fftshift` — centres low-frequency content for spatially-consistent conv filters\n3. `log1p` — compresses extreme dynamic range of FFT magnitudes\n4. Two Conv2D + BatchNorm + MaxPool blocks\n5. Fully connected → 128-dim feature vector\n\n### Two-Phase Training\n\n| Phase | Epochs | LR | Backbone |\n|---|---|---|---|\n| Phase 1 (warm-up) | 1–5 | 1e-4 | Fully frozen |\n| Phase 2 (fine-tune) | 6+ | 1e-5 | Last 2 blocks unfrozen |\n\n---\n\n## 📊 Evaluation Metrics\n\n| Metric | Description |\n|---|---|\n| Accuracy | Overall correct classifications |\n| Precision | Of predicted fakes, how many were actually fake |\n| Recall | Of actual fakes, how many were caught |\n| F1 Score | Harmonic mean of precision and recall |\n| Confusion Matrix | True/False Positive/Negative breakdown |\n\n---\n\n## 🌐 Applications\n\n- Social media content verification\n- News authenticity validation\n- Digital identity protection\n- Cybercrime and fraud detection\n- Media forensics and journalism\n\n---\n\n## 🔮 Future Enhancements\n\n- Temporal modeling with 3D CNN or Vision Transformer across video frames\n- Audio-visual consistency check (voice + face sync)\n- Browser extension for in-page detection\n- Mobile deployment (CoreML / TFLite)\n- Confidence calibration and uncertainty estimation\n\n---\n\n## 📜 License\n\nThis project is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpriyankagnana%2Fdeepshield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpriyankagnana%2Fdeepshield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpriyankagnana%2Fdeepshield/lists"}