Feature: Add Media Forensics shard

.env.example

@@ -103,6 +103,25 @@ POSTGRES_DB=arkhamdb
 # Only set if using an external Redis instance:
 # REDIS_URL=redis://your-redis-host:6379
 
+# -----------------------------------------------------------------------------
+# Media Forensics - Reverse Image Search API Keys (Optional)
+# -----------------------------------------------------------------------------
+# These API keys enable automated reverse image search functionality.
+# Without them, the Media Forensics shard still provides clickable URLs
+# for manual reverse image searches on Google, TinEye, Yandex, and Bing.
+
+# TinEye API - Commercial reverse image search
+# Sign up at: https://tineye.com/developers
+# TINEYE_API_KEY=your-tineye-api-key
+
+# Google Cloud Vision API - Image analysis and web detection
+# Enable at: https://console.cloud.google.com/apis/library/vision.googleapis.com
+# GOOGLE_VISION_API_KEY=your-google-vision-api-key
+
+# SerpAPI - Google Images search results (has free tier)
+# Sign up at: https://serpapi.com/
+# SERPAPI_KEY=your-serpapi-key
+
 # -----------------------------------------------------------------------------
 # Production HTTPS (Traefik) - Optional
 # -----------------------------------------------------------------------------

Dockerfile

@@ -78,6 +78,7 @@ COPY packages/arkham-shard-settings/ ./packages/arkham-shard-settings/
 COPY packages/arkham-shard-summary/ ./packages/arkham-shard-summary/
 COPY packages/arkham-shard-templates/ ./packages/arkham-shard-templates/
 COPY packages/arkham-shard-timeline/ ./packages/arkham-shard-timeline/
+COPY packages/arkham-shard-media-forensics/ ./packages/arkham-shard-media-forensics/
 
 # Install CPU-only PyTorch BEFORE shards to avoid downloading ~3GB of CUDA libraries
 # This must come before sentence-transformers (used by arkham-shard-embed)
@@ -147,6 +148,7 @@ COPY packages/arkham-shard-settings/shard.yaml /app/manifests/settings.yaml
 COPY packages/arkham-shard-summary/shard.yaml /app/manifests/summary.yaml
 COPY packages/arkham-shard-templates/shard.yaml /app/manifests/templates.yaml
 COPY packages/arkham-shard-timeline/shard.yaml /app/manifests/timeline.yaml
+COPY packages/arkham-shard-media-forensics/shard.yaml /app/manifests/media-forensics.yaml
 
 WORKDIR /app
 

README.md

@@ -57,6 +57,11 @@ Hybrid semantic/keyword search with built-in regex patterns for PII, financial d
 
 ![Search](docs/Screens/regex.png)
 
+### Media Forensics
+Image authenticity analysis with EXIF extraction, Error Level Analysis (ELA), perceptual hashing, and reverse image search integration.
+
+![Media Forensics](docs/Screens/mediaforensics.png)
+
 </details>
 
 ---
@@ -113,7 +118,7 @@ SHATTERED uses the **Voltron** architectural philosophy: a modular, plug-and-pla
         +--------------------+--------------------+
         |         |          |          |         |
    +----v----+ +--v--+ +-----v-----+ +--v--+ +---v---+
-   |Dashboard| | ACH | |  Search   | |Graph| |Timeline|  <-- SHARDS (25)
+   |Dashboard| | ACH | |  Search   | |Graph| |Timeline|  <-- SHARDS (26)
    +---------+ +-----+ +-----------+ +-----+ +--------+
 ```
 
@@ -268,7 +273,7 @@ The Frame provides 17 core services available to all shards:
 |-------|-------------|--------------|
 | **Search** | Document search | Semantic, keyword, hybrid search, facets, suggestions |
 
-### Analysis (8 shards)
+### Analysis (9 shards)
 
 | Shard | Description | Key Features |
 |-------|-------------|--------------|
@@ -280,6 +285,7 @@ The Frame provides 17 core services available to all shards:
 | **Patterns** | Pattern recognition | Recurring, behavioral, temporal, correlation patterns |
 | **Provenance** | Evidence chains | Data lineage, audit trails, artifact verification |
 | **Summary** | Auto-summarization | Multiple summary types, batch processing, auto-summarize on ingest |
+| **Media Forensics** | Image authenticity analysis | EXIF extraction, ELA analysis, perceptual hashing, C2PA verification, reverse image search |
 
 ### Visualization (2 shards)
 
@@ -332,6 +338,7 @@ The Frame provides 17 core services available to all shards:
 | **NER** | spaCy (en_core_web_sm/lg/trf) |
 | **OCR** | PaddleOCR, Vision LLM (Qwen-VL local, or cloud GPT-4o/Claude) |
 | **Embeddings** | sentence-transformers, OpenAI |
+| **Reverse Image Search** | TinEye, Google Vision, SerpAPI (optional APIs for Media Forensics) |
 
 ---
 
@@ -782,7 +789,7 @@ Each shard has its own README with API documentation, events, and usage examples
 | Metric | Value |
 |--------|-------|
 | **Lines of Code** | ~217,000 |
-| **Total Packages** | 26 (25 shards + shell) |
+| **Total Packages** | 27 (26 shards + shell) |
 | **Frame Services** | 17 |
 | **API Endpoints** | 400+ |
 | **Graph Visualization Modes** | 10+ |

docker-compose.yml

@@ -40,7 +40,7 @@ services:
       # Recommended: BAAI/bge-m3 (1024 dims, ~2.2GB, high quality)
       # Lightweight: all-MiniLM-L6-v2 (384 dims, ~80MB, fast)
       # WARNING: Once set, changing models requires rebuilding vector collections
-      - EMBED_MODEL=${EMBED_MODEL:-}
+      - EMBED_MODEL=${EMBED_MODEL:-all-MiniLM-L6-v2}
       # Serve the React shell from FastAPI
       - ARKHAM_SERVE_SHELL=true
       # Auth security (REQUIRED for production - generate with: openssl rand -hex 32)

packages/arkham-shard-media-forensics/README.md

@@ -0,0 +1,137 @@
+# Media Forensics Shard
+
+Media metadata extraction and forensic analysis for images within the SHATTERED framework.
+
+## Overview
+
+The Media Forensics shard provides comprehensive image authenticity analysis capabilities, including:
+
+- **EXIF Extraction**: Extract and analyze embedded metadata from images (camera info, GPS, timestamps)
+- **Perceptual Hashing**: Generate perceptual hashes for image similarity detection
+- **C2PA Verification**: Verify Content Authenticity Initiative (C2PA) provenance data
+- **ELA Analysis**: Error Level Analysis to detect potential image manipulation
+- **Sun Position Verification**: Cross-reference claimed photo timestamps with calculated sun positions
+- **Similar Image Detection**: Find visually similar images across the document corpus
+- **Reverse Image Search**: Search for image appearances across the web
+
+## Installation
+
+```bash
+cd packages/arkham-shard-media-forensics
+pip install -e .
+
+# For C2PA support (optional)
+pip install -e ".[c2pa]"
+```
+
+## Dependencies
+
+- **arkham-frame**: Core framework (required)
+- **Pillow**: Image processing
+- **exifread**: EXIF metadata extraction
+- **pysolar**: Sun position calculations
+- **scipy**: Scientific computing for ELA
+- **c2pa-python**: C2PA verification (optional)
+
+## Configuration
+
+### Reverse Image Search API Keys (Optional)
+
+The similar image search feature works in two modes:
+
+1. **Without API Keys (Default)**: Generates clickable URLs to perform manual reverse image searches on:
+   - Google Lens
+   - Google Images
+   - TinEye
+   - Yandex Images
+   - Bing Visual Search
+
+2. **With API Keys**: Enables automated reverse image search with results returned directly in the UI.
+
+#### Available API Keys
+
+Add these to your `.env` file or `docker-compose.yml` environment section:
+
+| Variable | Service | Cost | Sign Up |
+|----------|---------|------|---------|
+| `TINEYE_API_KEY` | TinEye | Paid | [tineye.com/developers](https://tineye.com/developers) |
+| `GOOGLE_VISION_API_KEY` | Google Cloud Vision | Free tier + paid | [Cloud Console](https://console.cloud.google.com/apis/library/vision.googleapis.com) |
+| `SERPAPI_KEY` | SerpAPI (Google Images) | Free tier (100/mo) | [serpapi.com](https://serpapi.com/) |
+
+#### Example Configuration
+
+**In `.env` file:**
+```bash
+# TinEye - Commercial reverse image search with extensive database
+TINEYE_API_KEY=your-tineye-api-key
+
+# Google Cloud Vision - Web detection and similar images
+GOOGLE_VISION_API_KEY=your-google-vision-api-key
+
+# SerpAPI - Google Images results (has free tier: 100 searches/month)
+SERPAPI_KEY=your-serpapi-key
+```
+
+**In `docker-compose.yml`:**
+```yaml
+services:
+  app:
+    environment:
+      - TINEYE_API_KEY=${TINEYE_API_KEY}
+      - GOOGLE_VISION_API_KEY=${GOOGLE_VISION_API_KEY}
+      - SERPAPI_KEY=${SERPAPI_KEY}
+```
+
+#### Recommended Setup
+
+For most users, we recommend:
+
+1. **Start without API keys** - The manual search URLs work well for occasional use
+2. **Add SerpAPI** if you need automated results - Their free tier (100 searches/month) is generous
+3. **Add TinEye** for professional use - Best database for finding image origins and modifications
+
+## API Endpoints
+
+All endpoints are prefixed with `/api/media-forensics/`:
+
+- `POST /analyze/{document_id}` - Run full forensic analysis on an image
+- `GET /analyses/{analysis_id}` - Get analysis results
+- `GET /analyses/count` - Get total analysis count (for navigation badge)
+- `GET /document/{document_id}/metadata` - Get extracted EXIF metadata
+- `GET /document/{document_id}/ela` - Get ELA analysis image
+- `GET /document/{document_id}/c2pa` - Get C2PA verification results
+- `POST /similar` - Find similar images by perceptual hash
+
+## Events
+
+### Published
+- `media.metadata.extracted` - EXIF/metadata extraction complete
+- `media.hash.computed` - Perceptual hash generated
+- `media.c2pa.verified` - C2PA verification complete
+- `media.ela.generated` - ELA analysis complete
+- `media.similar.found` - Similar images detected
+
+### Subscribed
+- `document.ingested` - Auto-analyze newly ingested images
+- `document.processed` - Process images after document processing
+
+## Architecture
+
+```
+arkham_shard_media_forensics/
+├── __init__.py          # Package exports
+├── shard.py             # Shard implementation
+├── api.py               # FastAPI routes
+├── models.py            # Pydantic models
+└── services/
+    ├── __init__.py
+    ├── exif_service.py      # EXIF extraction
+    ├── hash_service.py      # Perceptual hashing
+    ├── c2pa_service.py      # C2PA verification
+    ├── ela_service.py       # Error Level Analysis
+    └── sun_service.py       # Sun position verification
+```
+
+## License
+
+MIT

packages/arkham-shard-media-forensics/arkham_shard_media_forensics/__init__.py

@@ -0,0 +1,6 @@
+"""ArkhamFrame Media Forensics Shard - Media metadata extraction and forensic analysis."""
+
+from .shard import MediaForensicsShard
+
+__version__ = "0.1.0"
+__all__ = ["MediaForensicsShard"]