Upload 9 files

Initial deployment: DeepGuard AI Forensics Backend

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies required for OpenCV and ONNX
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy all backend files into the container
+COPY . .
+
+# Download the ONNX model inside the cloud container
+RUN python download_model.py
+
+# Expose the port FastAPI runs on
+EXPOSE 8000
+
+# Command to run the application (Hugging Face Spaces expects 0.0.0.0)
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary.
+
+You are permitted to view the source code for educational or portfolio evaluation purposes.
+
+However, you may NOT use, copy, modify, distribute, or run this Software without explicit, written permission from the author. 
+
+If permission is granted by the author, you MUST give full credit and attribution to the original author in any public display or distribution of the work.
+
+To request permission for use, please contact the author directly.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE.

download_model.py

@@ -0,0 +1,93 @@
+"""
+DeepGuard — Model Download Script
+Downloads the ViT-based deepfake detection ONNX model from Hugging Face Hub.
+
+Usage:
+    python download_model.py
+
+Model: onnx-community/Deep-Fake-Detector-v2-Model-ONNX
+  - Architecture: google/vit-base-patch16-224-in21k (fine-tuned)
+  - Task:         Binary classification — Realism vs. Deepfake
+  - Labels:       {0: "Realism", 1: "Deepfake"}
+"""
+
+import os
+import sys
+import hashlib
+
+MODELS_DIR = os.path.join(os.path.dirname(__file__), "models")
+MODEL_DEST = os.path.join(MODELS_DIR, "deepfake_vit.onnx")
+
+REPO_ID = "onnx-community/Deep-Fake-Detector-v2-Model-ONNX"
+FILENAME = "onnx/model.onnx"  # Path inside the HF repo
+
+
+def sha256(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def download():
+    os.makedirs(MODELS_DIR, exist_ok=True)
+
+    if os.path.exists(MODEL_DEST):
+        size_mb = os.path.getsize(MODEL_DEST) / (1024 * 1024)
+        print(f"[DeepGuard] Model already exists ({size_mb:.1f} MB): {MODEL_DEST}")
+        print(f"[DeepGuard] SHA-256: {sha256(MODEL_DEST)}")
+        print("[DeepGuard] Delete the file and re-run this script to force re-download.")
+        return
+
+    print(f"[DeepGuard] Downloading model from Hugging Face Hub...")
+    print(f"  Repo:    {REPO_ID}")
+    print(f"  File:    {FILENAME}")
+    print(f"  Target:  {MODEL_DEST}")
+    print()
+
+    try:
+        from huggingface_hub import hf_hub_download
+
+        tmp_path = hf_hub_download(
+            repo_id=REPO_ID,
+            filename=FILENAME,
+            cache_dir=MODELS_DIR,
+            local_dir=MODELS_DIR,
+            local_dir_use_symlinks=False,
+        )
+
+        # hf_hub_download writes to local_dir/<filename>
+        # Move if needed
+        expected_local = os.path.join(MODELS_DIR, "onnx", "model.onnx")
+        if os.path.exists(expected_local) and not os.path.exists(MODEL_DEST):
+            import shutil
+            shutil.move(expected_local, MODEL_DEST)
+
+        if not os.path.exists(MODEL_DEST):
+            # Try symlink/copy from tmp_path
+            import shutil
+            shutil.copy2(tmp_path, MODEL_DEST)
+
+        size_mb = os.path.getsize(MODEL_DEST) / (1024 * 1024)
+        checksum = sha256(MODEL_DEST)
+        print(f"\n[DeepGuard] [OK] Download complete!")
+        print(f"  Size:    {size_mb:.1f} MB")
+        print(f"  SHA-256: {checksum}")
+        print(f"  Path:    {MODEL_DEST}")
+
+    except ImportError:
+        print("[ERROR] huggingface_hub not installed. Run: pip install huggingface_hub")
+        sys.exit(1)
+    except Exception as e:
+        print(f"[ERROR] Download failed: {e}")
+        print()
+        print("Manual download instructions:")
+        print(f"  1. Visit: https://huggingface.co/{REPO_ID}/tree/main/onnx")
+        print(f"  2. Download 'model.onnx'")
+        print(f"  3. Place it at: {MODEL_DEST}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    download()

ela.py

@@ -0,0 +1,51 @@
+import io
+import base64
+from PIL import Image, ImageChops, ImageEnhance
+
+def generate_ela(image: Image.Image, quality: int = 90, scale: float = 15.0) -> str:
+    """
+    Performs Error Level Analysis (ELA) on an image to highlight manipulated regions.
+    Saves the image as a temporary JPEG at a specific quality level and compares
+    it with the original to find compression differences.
+
+    Args:
+        image: Original PIL Image.
+        quality: JPEG compression quality for the resaved image (default 90).
+        scale: Brightness multiplier to make the differences visible (default 15.0).
+        
+    Returns:
+        Base64-encoded string of the ELA image.
+    """
+    try:
+        # Convert to RGB if necessary
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+            
+        # 1. Resave the image in memory at a specific quality
+        temp_buffer = io.BytesIO()
+        image.save(temp_buffer, "JPEG", quality=quality)
+        temp_buffer.seek(0)
+        
+        # 2. Open the resaved image
+        resaved_img = Image.open(temp_buffer)
+        
+        # 3. Calculate the absolute difference between original and resaved
+        # Manipulated areas will stand out because they compress differently
+        ela_img = ImageChops.difference(image, resaved_img)
+        
+        # 4. Enhance the difference (brightness) so it's visible to the human eye
+        enhancer = ImageEnhance.Brightness(ela_img)
+        ela_enhanced = enhancer.enhance(scale)
+        
+        # 5. Convert to Base64 for the frontend
+        out_buffer = io.BytesIO()
+        ela_enhanced.save(out_buffer, format="JPEG", quality=85)
+        out_buffer.seek(0)
+        base64_str = base64.b64encode(out_buffer.read()).decode("utf-8")
+        
+        return f"data:image/jpeg;base64,{base64_str}"
+        
+    except Exception as e:
+        print(f"[DeepGuard] ELA Generation Error: {e}")
+        # Return empty string on failure
+        return ""

heatmap.py

@@ -0,0 +1,220 @@
+"""
+DeepGuard — Heatmap Generation Module
+
+Strategy:
+  1. PRIMARY:  Attention Rollout — extract multi-head attention matrices from
+               ONNX intermediate outputs and roll them up through all layers.
+  2. FALLBACK: Frequency Anomaly + Gradient Saliency — if attention weights
+               are not exported, compute a forensically meaningful heatmap
+               using DCT frequency analysis and Sobel edge gradients.
+               (Pure NumPy, <10ms, no additional inference passes.)
+"""
+
+import io
+import numpy as np
+from PIL import Image
+from scipy.ndimage import gaussian_filter
+import base64
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def generate_heatmap(
+    image: Image.Image,
+    output_dict: dict,
+    confidence_score: float,
+) -> str:
+    """
+    Generate a transparent red/yellow heatmap overlay.
+
+    Args:
+        image:            Original PIL image (any size).
+        output_dict:      Raw ONNX output dict {name: ndarray}.
+        confidence_score: Model fake probability [0, 1].
+
+    Returns:
+        data URI string: "data:image/png;base64,..."
+    """
+    img224 = image.convert("RGB").resize((224, 224), Image.BILINEAR)
+    img_arr = np.array(img224, dtype=np.float32)
+
+    # Try attention rollout first
+    attn_keys = [
+        k for k in output_dict
+        if "attn" in k.lower() or "attention" in k.lower()
+    ]
+
+    heat_map = None
+    if attn_keys:
+        heat_map = _attention_rollout(output_dict, attn_keys)
+
+    if heat_map is None:
+        heat_map = _frequency_saliency(img_arr, confidence_score)
+
+    overlay = _apply_overlay(img_arr, heat_map)
+    return _encode_png(overlay)
+
+
+# ---------------------------------------------------------------------------
+# Strategy 1: Attention Rollout
+# ---------------------------------------------------------------------------
+
+def _attention_rollout(output_dict: dict, attn_keys: list) -> Optional[np.ndarray]:
+    """
+    Roll up multi-head attention matrices across all transformer layers.
+    Returns a normalized (224, 224) float32 array or None on failure.
+    """
+    try:
+        # Sort keys to ensure layer order (layer_0, layer_1, ...)
+        attn_keys_sorted = sorted(attn_keys)
+        rollout = None
+
+        for key in attn_keys_sorted:
+            attn = output_dict[key]  # Expected shape: (1, heads, seq_len, seq_len)
+            if attn.ndim != 4:
+                continue
+            attn = attn.squeeze(0)                  # (heads, seq_len, seq_len)
+            attn = attn.mean(axis=0)                # Average heads → (seq_len, seq_len)
+
+            # Add residual identity (attention rollout formula)
+            identity = np.eye(attn.shape[0], dtype=np.float32)
+            attn = 0.5 * attn + 0.5 * identity
+            attn = attn / (attn.sum(axis=-1, keepdims=True) + 1e-8)
+
+            rollout = attn if rollout is None else np.matmul(rollout, attn)
+
+        if rollout is None:
+            return None
+
+        # Row 0 = CLS token → attends to all patch tokens
+        cls_attn = rollout[0, 1:]  # Drop CLS itself → (num_patches,)
+        num_patches = cls_attn.shape[0]
+        side = int(np.sqrt(num_patches))  # 14 for ViT-base-patch16
+
+        if side * side != num_patches:
+            return None
+
+        patch_map = cls_attn.reshape(side, side)
+        patch_map = (patch_map - patch_map.min()) / (patch_map.max() - patch_map.min() + 1e-8)
+
+        # Upsample to 224×224
+        heat = _upsample(patch_map, 224, 224)
+        heat = gaussian_filter(heat, sigma=8)
+        return _normalize(heat)
+
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Strategy 2: Frequency Anomaly + Sobel Saliency (pure NumPy fallback)
+# ---------------------------------------------------------------------------
+
+def _frequency_saliency(img_arr: np.ndarray, confidence_score: float) -> np.ndarray:
+    """
+    Generate a heatmap from:
+      - DCT/FFT frequency anomalies (AI images have characteristic frequency patterns)
+      - Sobel gradient magnitude (AI fails at object/background boundaries)
+
+    Both signals are combined and weighted by the confidence score.
+    """
+    gray = 0.299 * img_arr[:, :, 0] + 0.587 * img_arr[:, :, 1] + 0.114 * img_arr[:, :, 2]
+    gray_norm = gray / 255.0
+
+    # --- Frequency anomaly via 2D FFT ---
+    fft = np.fft.fft2(gray_norm)
+    fft_shift = np.fft.fftshift(fft)
+    magnitude = np.log1p(np.abs(fft_shift))
+    # High-pass: keep frequencies above the center radius (AI images often
+    # have unnaturally suppressed high-frequency noise)
+    h, w = magnitude.shape
+    cy, cx = h // 2, w // 2
+    Y, X = np.ogrid[:h, :w]
+    r = np.sqrt((X - cx) ** 2 + (Y - cy) ** 2)
+    # Anomaly score: deviation of high-freq energy from expected camera noise
+    high_freq_mask = r > (min(h, w) * 0.15)
+    freq_baseline = magnitude[high_freq_mask].mean()
+    freq_map = np.abs(magnitude - freq_baseline)
+    freq_map = _normalize(freq_map)
+
+    # --- Sobel gradient magnitude ---
+    ky = np.array([[-1, -2, -1], [0, 0, 0], [1, 2, 1]], dtype=np.float32)
+    kx = ky.T
+    gx = _convolve2d(gray_norm, kx)
+    gy = _convolve2d(gray_norm, ky)
+    grad_map = np.sqrt(gx ** 2 + gy ** 2)
+    grad_map = _normalize(grad_map)
+
+    # Combine: weight by score — high-confidence → emphasize freq anomaly
+    alpha = min(confidence_score * 1.2, 0.8)
+    combined = alpha * freq_map + (1.0 - alpha) * grad_map
+
+    # Smooth and normalize
+    combined = gaussian_filter(combined, sigma=10)
+    return _normalize(combined)
+
+
+def _convolve2d(img: np.ndarray, kernel: np.ndarray) -> np.ndarray:
+    """Manual 2D convolution via stride tricks (no scipy dependency for this)."""
+    from scipy.ndimage import convolve
+    return convolve(img, kernel, mode="reflect")
+
+
+# ---------------------------------------------------------------------------
+# Colormap and overlay helpers
+# ---------------------------------------------------------------------------
+
+def _apply_overlay(img_arr: np.ndarray, heat: np.ndarray, alpha: float = 0.55) -> np.ndarray:
+    """
+    Blend red/yellow heatmap over original image.
+    Returns RGBA uint8 array (224, 224, 4).
+    """
+    # Map heat [0,1] to RGBA: 0=transparent, 0.5=orange, 1.0=bright red
+    r = np.ones_like(heat)                              # R channel: always full
+    g = np.clip(1.0 - heat * 1.4, 0, 1)                # G: fades out → red
+    b = np.zeros_like(heat)                             # B: always 0
+
+    overlay_rgb = np.stack([r, g, b], axis=-1)          # (224,224,3) float [0,1]
+    overlay_alpha = np.clip(heat * alpha * 255, 0, 255) # (224,224) float
+
+    # Blend: result = img * (1 - a) + color * a
+    a3 = (overlay_alpha[:, :, np.newaxis] / 255.0)
+    blended = (img_arr / 255.0) * (1.0 - a3) + overlay_rgb * a3
+    blended = np.clip(blended * 255, 0, 255).astype(np.uint8)
+
+    # Add alpha channel
+    alpha_ch = overlay_alpha.astype(np.uint8)
+    # Keep full opacity everywhere, just use blend for color
+    full_alpha = np.full((224, 224), 255, dtype=np.uint8)
+    rgba = np.dstack([blended, full_alpha])
+    return rgba
+
+
+def _encode_png(rgba_arr: np.ndarray) -> str:
+    """Encode RGBA array to data URI."""
+    pil_img = Image.fromarray(rgba_arr, mode="RGBA")
+    buf = io.BytesIO()
+    pil_img.save(buf, format="PNG", optimize=True)
+    b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
+    return f"data:image/png;base64,{b64}"
+
+
+# ---------------------------------------------------------------------------
+# Utility helpers
+# ---------------------------------------------------------------------------
+
+def _normalize(arr: np.ndarray) -> np.ndarray:
+    mn, mx = arr.min(), arr.max()
+    if mx - mn < 1e-8:
+        return np.zeros_like(arr, dtype=np.float32)
+    return ((arr - mn) / (mx - mn)).astype(np.float32)
+
+
+def _upsample(patch_map: np.ndarray, target_h: int, target_w: int) -> np.ndarray:
+    """Bilinear upsample a small 2D patch map to target size using PIL."""
+    pil = Image.fromarray((patch_map * 255).astype(np.uint8), mode="L")
+    pil = pil.resize((target_w, target_h), Image.BILINEAR)
+    return np.array(pil, dtype=np.float32) / 255.0

inference.py

@@ -0,0 +1,169 @@
+"""
+DeepGuard — ONNX ViT Inference Module
+Loads the deepfake detection model once at startup.
+All inference is stateless and in-memory.
+
+Model: onnx-community/Deep-Fake-Detector-v2-Model-ONNX
+  - Architecture: google/vit-base-patch16-224
+  - Labels: {0: "Realism", 1: "Deepfake"}
+  - Input:  pixel_values  (1, 3, 224, 224) float32
+  - Output: logits        (1, 2)           float32
+"""
+
+import os
+import io
+import numpy as np
+from PIL import Image
+from typing import Optional, Tuple
+import onnxruntime as ort
+
+# ImageNet normalization constants (used during ViT pre-training)
+IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+IMAGENET_STD  = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+MODEL_PATH = os.path.join(os.path.dirname(__file__), "models", "deepfake_vit.onnx")
+
+# Module-level singleton — loaded once, reused for every request
+_session: Optional[ort.InferenceSession] = None
+_input_name: str = ""
+_output_names: list[str] = []
+_has_attention_outputs: bool = False
+
+
+def load_model() -> None:
+    """
+    Load the ONNX model into a global session at startup.
+    Must be called once before any inference.
+    """
+    global _session, _input_name, _output_names, _has_attention_outputs
+
+    if not os.path.exists(MODEL_PATH):
+        raise FileNotFoundError(
+            f"Model not found at {MODEL_PATH}. "
+            "Please run: python download_model.py"
+        )
+
+    opts = ort.SessionOptions()
+    opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+    opts.inter_op_num_threads = 4
+    opts.intra_op_num_threads = 4
+
+    _session = ort.InferenceSession(
+        MODEL_PATH,
+        sess_options=opts,
+        providers=["CPUExecutionProvider"],
+    )
+
+    _input_name = _session.get_inputs()[0].name
+    _output_names = [o.name for o in _session.get_outputs()]
+
+    # Check whether model exposes attention weights (for attention rollout heatmap)
+    _has_attention_outputs = any(
+        "attn" in n.lower() or "attention" in n.lower()
+        for n in _output_names
+    )
+
+    print(f"[DeepGuard] Model loaded: {MODEL_PATH}")
+    print(f"[DeepGuard] Input:   {_input_name}")
+    print(f"[DeepGuard] Outputs: {_output_names}")
+    print(f"[DeepGuard] Attention outputs available: {_has_attention_outputs}")
+
+
+def get_session() -> ort.InferenceSession:
+    if _session is None:
+        raise RuntimeError("Model not loaded. Call load_model() first.")
+    return _session
+
+
+def has_attention_outputs() -> bool:
+    return _has_attention_outputs
+
+
+def get_attention_output_names() -> list[str]:
+    return [n for n in _output_names if "attn" in n.lower() or "attention" in n.lower()]
+
+
+def preprocess(image: Image.Image) -> np.ndarray:
+    """
+    Preprocess a PIL Image for ViT inference.
+    Returns: float32 NCHW tensor of shape (1, 3, 224, 224)
+    """
+    img = image.convert("RGB").resize((224, 224), Image.BILINEAR)
+    arr = np.array(img, dtype=np.float32) / 255.0          # (224, 224, 3)  [0, 1]
+    arr = (arr - IMAGENET_MEAN) / IMAGENET_STD              # Normalize
+    arr = arr.transpose(2, 0, 1)                            # HWC → CHW
+    arr = np.expand_dims(arr, axis=0)                       # CHW → NCHW (1,3,224,224)
+    return arr
+
+
+def softmax(logits: np.ndarray) -> np.ndarray:
+    """Numerically stable softmax."""
+    e = np.exp(logits - np.max(logits))
+    return e / e.sum()
+
+
+def run_inference(image: Image.Image) -> Tuple[float, dict]:
+    """
+    Run the deepfake detection model on a PIL image.
+
+    Returns:
+        confidence_score (float): Probability of being AI-generated [0.0, 1.0]
+        raw_outputs (dict):       Full ONNX output dict (for heatmap module)
+    """
+    session = get_session()
+    tensor = preprocess(image)
+
+    # Run with all outputs (logits + any attention matrices)
+    raw_outputs = session.run(None, {_input_name: tensor})
+    output_dict = dict(zip(_output_names, raw_outputs))
+
+    # Find logits output (first non-attention output, or output named 'logits')
+    logits_key = next(
+        (n for n in _output_names if "logit" in n.lower()),
+        _output_names[0]
+    )
+    logits = output_dict[logits_key].squeeze()  # shape (2,)
+
+    probs = softmax(logits)
+    # Label mapping: {0: "Realism", 1: "Deepfake"}
+    confidence_score = float(probs[1])   # probability of being Deepfake
+
+    return confidence_score, output_dict
+
+
+def get_threat_level(score: float) -> str:
+    """Map confidence score to threat level label."""
+    if score >= 0.90:
+        return "CRITICAL"
+    elif score >= 0.75:
+        return "HIGH"
+    elif score >= 0.50:
+        return "MEDIUM"
+    else:
+        return "LOW"
+
+
+def get_model_reasoning(score: float, has_exif: bool, software: str) -> str:
+    """Generate a human-readable model reasoning string."""
+    reasons = []
+
+    if score >= 0.90:
+        reasons.append("Very high-confidence AI artifact signatures detected across multiple image regions.")
+    elif score >= 0.75:
+        reasons.append("Significant statistical anomalies inconsistent with optical camera sensors detected.")
+    elif score >= 0.50:
+        reasons.append("Moderate AI artifact patterns detected; image may be partially manipulated.")
+    else:
+        reasons.append("Low probability of AI generation; image statistics consistent with real photography.")
+
+    if not has_exif:
+        reasons.append("Absence of EXIF metadata is a strong AI indicator.")
+    if software != "None":
+        reasons.append(f"Known AI software tag '{software}' detected in image metadata.")
+
+    reasons.append(
+        "ViT attention model flagged inconsistencies in background frequency, "
+        "texture uniformity, and facial boundary regions."
+    )
+
+    return " ".join(reasons)

main.py

@@ -0,0 +1,217 @@
+"""
+DeepGuard — FastAPI Backend
+Real-time, stateless deepfake detection API.
+
+Endpoints:
+  GET  /health   — Liveness check (used by extension popup)
+  POST /analyze  — Analyze an image for AI-generation artifacts
+
+All data is processed in RAM and dropped immediately after the response.
+"""
+
+import io
+import base64
+import traceback
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from PIL import Image
+
+import inference
+import metadata as meta_module
+import heatmap as heatmap_module
+
+
+# ---------------------------------------------------------------------------
+# Lifespan: load model once at startup
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("[DeepGuard] Starting up — loading ONNX model...")
+    try:
+        inference.load_model()
+        print("[DeepGuard] Model ready. Server is live at http://localhost:8000")
+    except FileNotFoundError as e:
+        print(f"[DeepGuard] WARNING: {e}")
+        print("[DeepGuard] Run 'python download_model.py' to fetch the model.")
+    yield
+    print("[DeepGuard] Shutting down.")
+
+
+# ---------------------------------------------------------------------------
+# App setup
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="DeepGuard API",
+    description="Real-time stateless deepfake detection using ViT + ONNX Runtime",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# Aggressive CORS — required because Chrome extensions use a chrome-extension:// origin
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+import ela as ela_module
+
+
+# ---------------------------------------------------------------------------
+# Request / Response schemas
+# ---------------------------------------------------------------------------
+
+class AnalyzeRequest(BaseModel):
+    image_data: str  # data:image/...;base64,<payload>  OR  raw base64
+
+
+class MetadataResult(BaseModel):
+    exif_data_present: bool
+    software_signature_found: str
+    warning: str
+
+
+class ForensicsResult(BaseModel):
+    model_reasoning: str
+    metadata: MetadataResult
+
+
+class AnalyzeResponse(BaseModel):
+    status: str
+    threat_level: str
+    confidence_score: float
+    heatmap_overlay_url: str
+    ela_overlay_url: str
+    forensics: ForensicsResult
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _decode_image(image_data: str) -> tuple[bytes, Image.Image]:
+    """
+    Decode a base64 data-URI or raw base64 string into (raw_bytes, PIL Image).
+    """
+    if image_data.startswith("data:"):
+        # Strip "data:image/jpeg;base64," prefix
+        header, b64_str = image_data.split(",", 1)
+    else:
+        b64_str = image_data
+
+    try:
+        raw_bytes = base64.b64decode(b64_str)
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid base64 image data.")
+
+    try:
+        image = Image.open(io.BytesIO(raw_bytes)).convert("RGB")
+    except Exception:
+        raise HTTPException(status_code=400, detail="Could not decode image from base64 payload.")
+
+    return raw_bytes, image
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/health")
+async def health():
+    """Liveness check. Returns model load status."""
+    try:
+        session = inference.get_session()
+        return {
+            "status": "ok",
+            "model_loaded": True,
+            "attention_heatmap": inference.has_attention_outputs(),
+        }
+    except RuntimeError:
+        return {
+            "status": "degraded",
+            "model_loaded": False,
+            "attention_heatmap": False,
+            "message": "Model not loaded. Run python download_model.py",
+        }
+
+
+@app.post("/analyze", response_model=AnalyzeResponse)
+async def analyze(request: AnalyzeRequest):
+    """
+    Main analysis endpoint.
+    Accepts a base64-encoded image and returns:
+      - Deepfake confidence score
+      - Threat level classification
+      - Grad-CAM / attention heatmap overlay (base64 PNG)
+      - EXIF metadata forensics
+    """
+    # ── 1. Decode image ──────────────────────────────────────────────────
+    try:
+        raw_bytes, image = _decode_image(request.image_data)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Image decode error: {e}")
+
+    # ── 2. Metadata forensics (DFIR) ���────────────────────────────────────
+    try:
+        forensic_meta = meta_module.extract_metadata(raw_bytes)
+    except Exception:
+        forensic_meta = {
+            "exif_data_present": False,
+            "software_signature_found": "None",
+            "warning": "Metadata extraction failed.",
+        }
+
+    # ── 3. AI inference ───────────────────────────────────────────────────
+    try:
+        confidence_score, output_dict = inference.run_inference(image)
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=503,
+            detail=f"Model not loaded: {e}. Run python download_model.py first.",
+        )
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=f"Inference error: {e}")
+
+    # ── 4. Heatmap & ELA generation ────────────────────────────────────────
+    try:
+        heatmap_url = heatmap_module.generate_heatmap(image, output_dict, confidence_score)
+    except Exception:
+        import traceback
+        traceback.print_exc()
+        # Fallback: return a 1×1 transparent PNG
+        heatmap_url = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+
+    # Run Error Level Analysis (ELA)
+    ela_url = ela_module.generate_ela(image)
+
+    # ── 5. Build response ─────────────────────────────────────────────────
+    threat_level = inference.get_threat_level(confidence_score)
+    model_reasoning = inference.get_model_reasoning(
+        confidence_score,
+        forensic_meta["exif_data_present"],
+        forensic_meta["software_signature_found"],
+    )
+
+    return AnalyzeResponse(
+        status="success",
+        threat_level=threat_level,
+        confidence_score=round(confidence_score, 4),
+        heatmap_overlay_url=heatmap_url,
+        ela_overlay_url=ela_url,
+        forensics=ForensicsResult(
+            model_reasoning=model_reasoning,
+            metadata=MetadataResult(**forensic_meta),
+        ),
+    )

metadata.py

@@ -0,0 +1,103 @@
+"""
+DeepGuard — Metadata Forensics Module
+Extracts EXIF data and checks for known AI software signatures.
+All processing is stateless and in-memory.
+"""
+
+import io
+import struct
+from typing import Optional
+from PIL import Image
+
+# Known AI generation software signatures to look for in EXIF/metadata
+AI_SIGNATURES = [
+    "DALL-E", "dall-e", "Midjourney", "midjourney",
+    "Stable Diffusion", "stable-diffusion", "StableDiffusion",
+    "Adobe Firefly", "firefly", "Sora", "sora",
+    "Imagen", "imagen", "Bing Image Creator",
+    "NightCafe", "Craiyon", "FLUX", "flux",
+    "Runway", "runway", "Pika", "pika",
+    "ComfyUI", "comfyui", "Automatic1111", "InvokeAI",
+    "NovelAI", "novelai", "Leonardo", "leonardo.ai",
+]
+
+
+def extract_metadata(image_bytes: bytes) -> dict:
+    """
+    Perform forensic metadata analysis on raw image bytes.
+
+    Returns:
+        dict with keys: exif_data_present, software_signature_found, warning
+    """
+    exif_present = False
+    software_found = "None"
+    warning = ""
+
+    try:
+        img = Image.open(io.BytesIO(image_bytes))
+        fmt = img.format or "UNKNOWN"
+
+        # --- EXIF analysis (JPEG / TIFF / WEBP) ---
+        exif_data = img._getexif() if hasattr(img, "_getexif") else None
+
+        if exif_data:
+            exif_present = True
+            # Tag 305 = Software, Tag 315 = Artist, Tag 270 = ImageDescription
+            tag_values = {
+                305: "Software",
+                315: "Artist",
+                270: "ImageDescription",
+                37510: "UserComment",
+            }
+            for tag_id, tag_name in tag_values.items():
+                val = exif_data.get(tag_id, "")
+                if isinstance(val, bytes):
+                    try:
+                        val = val.decode("utf-8", errors="ignore")
+                    except Exception:
+                        val = ""
+                val_str = str(val)
+                for sig in AI_SIGNATURES:
+                    if sig.lower() in val_str.lower():
+                        software_found = sig
+                        break
+                if software_found != "None":
+                    break
+        else:
+            # Try PIL's generic info dict (PNG tEXt chunks, etc.)
+            info = getattr(img, "info", {})
+            if info:
+                exif_present = True  # Has some metadata
+                info_str = " ".join(str(v) for v in info.values())
+                for sig in AI_SIGNATURES:
+                    if sig.lower() in info_str.lower():
+                        software_found = sig
+                        break
+            else:
+                exif_present = False
+
+        # Build warning message
+        if not exif_present:
+            warning = (
+                "EXIF data missing. This is a strong indicator of synthesized media — "
+                "AI generators strip or never write camera metadata."
+            )
+        elif software_found != "None":
+            warning = (
+                f"AI software signature detected: '{software_found}'. "
+                "This image was almost certainly generated by an AI tool."
+            )
+        else:
+            warning = (
+                "EXIF data present. Metadata appears consistent with a camera-captured image, "
+                "but AI-generated images can be post-processed to include fake EXIF."
+            )
+
+    except Exception as e:
+        warning = f"Metadata parsing error: {str(e)}"
+
+    return {
+        "exif_data_present": exif_present,
+        "software_signature_found": software_found,
+        "warning": warning,
+    }

requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+onnxruntime==1.19.2
+Pillow==10.4.0
+numpy==1.26.4
+piexif==1.1.3
+scipy==1.14.1
+python-multipart==0.0.9
+huggingface_hub==0.24.6
+requests==2.32.3