ImageOSINT is a production-ready, distributed OSINT (Open Source Intelligence) platform for advanced image analysis. It combines reverse image searching, EXIF metadata extraction, geolocation analysis, and Google Maps intelligence gathering into a scalable web application.

Built with FastAPI, PostgreSQL, Redis, and Celery, ImageOSINT processes image analysis asynchronously at scale with real-time job monitoring, intelligent caching, and comprehensive result persistence.

• Multi-engine search: Google, Bing, Yandex simultaneously
• Parallel processing: Concurrent engine queries for fast results
• Result caching: 24-hour cache to reduce API calls
• Search history: Track and manage previous searches
• Smart deduplication: Eliminate redundant results automatically

• Complete metadata parsing: Extract 100+ EXIF fields
• GPS coordinate detection: Automatic GPS extraction from images
• Camera identification: Model, lens, and settings analysis
• Timestamp analysis: Creation date and modification tracking
• Format detection: Identify image type and compression data
• Advanced analysis: Hash-based image identification

• Reverse geocoding: GPS coordinates → Street addresses
• Forward geocoding: Location names → Precise coordinates
• Accuracy estimation: Confidence scoring for location data
• Location caching: 7-day cache for geolocation results
• Radius-based search: Find places within specified distance
• Multi-source verification: Cross-reference multiple sources

• Nearby places search: Restaurants, hotels, attractions
• Category-based queries: Business type filtering
• Street View metadata: Extract visual verification data
• Smart caching: 7-day cache for maps data
• Radius analysis: Configurable search distances
• Place details: Comprehensive business information

• Async task processing: Celery-based distributed queue
• Real-time monitoring: Job status with 0-100% progress tracking
• Result persistence: PostgreSQL storage with transaction safety
• Multi-level caching: Redis + in-memory fallback
• User management: Registration, login, JWT authentication
• API key support: Programmatic access for integrations
• Rate limiting: Built-in request throttling
• Health checks: Comprehensive service monitoring

• Horizontal scaling: Drop-in worker pool expansion
• Connection pooling: Optimized database connections
• Parallel processing: Concurrent image analysis
• Load balancing: Ready for production load distribution
• Performance metrics: Detailed analytics and statistics
• Auto-cleanup: Scheduled maintenance tasks

• JWT tokens: Secure token-based authentication
• Password hashing: Bcrypt with salt
• API keys: Long-lived programmatic access
• CORS configuration: Flexible cross-origin support
• SQL injection protection: ORM-based query safety
• Rate limiting: DDoS mitigation
• Request validation: Pydantic-based schema validation

• Gradio interface: Interactive web frontend
• Real-time updates: Live job status monitoring
• Multi-tab layout: Organized workflow
• API documentation: Auto-generated OpenAPI docs
• Swagger UI: Interactive API testing
• ReDoc: Beautiful API documentation

• Docker support: Production-ready containers
• Docker Compose: Single-command orchestration
• 6-service stack: PostgreSQL, Redis, API, Worker, Beat, Frontend
• Health checks: Automatic service monitoring
• Volume persistence: Data durability
• Development mode: Live reload for development

# Clone repository
git clone https://github.com/QusaiALBahri/imageOSINT.git
cd imageOSINT

# Start all services
docker-compose up -d

# Services available at:
# Frontend:  http://localhost:7860
# API Docs:  http://localhost:8000/api/docs
# Monitor:   http://localhost:5555

# Install dependencies
pip install -r requirements-backend.txt

# Start PostgreSQL (Docker)
docker run -d -p 5432:5432 \
  -e POSTGRES_PASSWORD=osint_password postgres:15-alpine

# Start Redis (Docker)
docker run -d -p 6379:6379 redis:7-alpine

# Initialize database
python -c "from database.init_db import init_db; init_db()"

# Start services (in separate terminals)
uvicorn backend.server:app --reload      # Terminal 1: API
celery -A tasks.celery worker           # Terminal 2: Worker
celery -A tasks.celery beat             # Terminal 3: Scheduler
python app_backend.py                   # Terminal 4: Frontend

# Using development Docker Compose
docker-compose -f docker-compose.dev.yml up -d

# Features:
# - Hot code reload
# - Debug logging
# - All endpoints accessible

┌─────────────────────────────────────────────────────────┐
│                    Client Applications                   │
│            (Gradio Frontend / External API Clients)      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
        ┌────────────────────────────┐
        │   FastAPI Server (8000)    │
        │  - JWT Authentication      │
        │  - Request Validation      │
        │  - Response Formatting     │
        └────────┬───────────────────┘
                 │
        ┌────────┴──────────┬──────────────┐
        ▼                   ▼              ▼
   ┌────────────┐   ┌──────────────┐  ┌──────────┐
   │ PostgreSQL │   │    Redis     │  │  Celery  │
   │  Database  │   │    Cache     │  │  Workers │
   └────────────┘   └──────────────┘  └─────┬────┘
                                             │
                                    ┌────────┴────────┐
                                    ▼                ▼
                            ┌──────────────┐  ┌────────────┐
                            │   Celery     │  │  Scheduled │
                            │   Beat       │  │   Tasks    │
                            └──────────────┘  └────────────┘

-- 7 Core Tables
UserAccount           -- User authentication & profiles
APIKey                -- API key management for programmatic access
AnalysisJob           -- Image analysis job tracking (status, progress)
SearchHistory         -- Reverse image search history
CachedResult          -- Result caching with TTL
LocationAnalysis      -- Geolocation data & reverse geocoding results
ImageMetadata         -- EXIF and image metadata storage

Authentication

POST   /api/auth/register              -- User registration
POST   /api/auth/login                 -- User login
GET    /api/auth/verify                -- Token verification

Image Analysis

POST   /api/analyze                    -- Submit image analysis job
GET    /api/analyze/{job_id}           -- Get job status & progress
GET    /api/analyze/{job_id}/results   -- Get analysis results

Reverse Image Search

POST   /api/search/reverse             -- Reverse search image
GET    /api/search/history             -- Get search history

Location Analysis

POST   /api/location/analyze           -- Analyze GPS coordinates
POST   /api/maps/nearby                -- Search nearby places

Task Management

GET    /api/tasks/{task_id}            -- Task status
GET    /api/tasks/{task_id}/results    -- Task results

Cache & Statistics

GET    /api/cache/stats                -- Cache statistics
DELETE /api/cache                      -- Clear cache
GET    /api/stats                      -- User statistics
GET    /health                         -- Health check

import requests
import json

BASE_URL = "http://localhost:8000"

# 1. Register
register_response = requests.post(
    f"{BASE_URL}/api/auth/register",
    json={
        "email": "user@example.com",
        "username": "testuser",
        "password": "SecurePass123!"
    }
)
token = register_response.json()["access_token"]

# 2. Submit Analysis
analysis_response = requests.post(
    f"{BASE_URL}/api/analyze",
    headers={"Authorization": f"Bearer {token}"},
    files={"file": open("image.jpg", "rb")},
    data={"analysis_types": ["metadata", "search", "location", "maps"]}
)
job_id = analysis_response.json()["job_id"]

# 3. Check Status
status_response = requests.get(
    f"{BASE_URL}/api/analyze/{job_id}",
    headers={"Authorization": f"Bearer {token}"}
)
print(f"Progress: {status_response.json()['progress']}%")

# 4. Get Results
results_response = requests.get(
    f"{BASE_URL}/api/analyze/{job_id}/results",
    headers={"Authorization": f"Bearer {token}"}
)
print(json.dumps(results_response.json(), indent=2))

const BASE_URL = "http://localhost:8000";

async function analyzeImage() {
  // Register
  const registerRes = await fetch(`${BASE_URL}/api/auth/register`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      username: "testuser",
      password: "SecurePass123!"
    })
  });
  const { access_token } = await registerRes.json();

  // Submit analysis
  const formData = new FormData();
  formData.append("file", imageFile);
  formData.append("analysis_types", [...selectedTypes]);

  const analysisRes = await fetch(`${BASE_URL}/api/analyze`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${access_token}` },
    body: formData
  });
  const { job_id } = await analysisRes.json();

  // Poll status
  const statusRes = await fetch(`${BASE_URL}/api/analyze/${job_id}`, {
    headers: { "Authorization": `Bearer ${access_token}` }
  });
  console.log(await statusRes.json());
}

# Register
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "testuser",
    "password": "SecurePass123!"
  }'

# Submit Analysis
curl -X POST http://localhost:8000/api/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@image.jpg" \
  -F "analysis_types=metadata" \
  -F "analysis_types=search" \
  -F "analysis_types=location" \
  -F "analysis_types=maps"

# Check Status
curl -X GET http://localhost:8000/api/analyze/{job_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get Results
curl -X GET http://localhost:8000/api/analyze/{job_id}/results \
  -H "Authorization: Bearer YOUR_TOKEN"

• Parallel task execution: Metadata + Search + Location + Maps run concurrently
• Result caching: 24-hour search cache, 7-day location/maps cache
• Database connection pooling: Pool size 20, overflow 40
• Worker concurrency: 4 workers by default, scalable
• Auto-retry: Failed tasks retry automatically

• ✅ JWT Authentication: Token-based request validation
• ✅ Password Hashing: Bcrypt with salt
• ✅ SQL Injection Protection: SQLAlchemy ORM parameterization
• ✅ CORS Policy: Configurable cross-origin requests
• ✅ Rate Limiting: Request throttling (1 req/sec default)
• ✅ Input Validation: Pydantic schema validation
• ✅ API Key Support: Long-lived tokens for programmatic access
• ✅ Secure Headers: HTTPS ready, security headers configured
• ✅ Audit Logging: Complete request/response logging
• ✅ Data Encryption: Support for encrypted database connections

imageOSINT/
├── backend/
│   ├── __init__.py
│   └── server.py                 # FastAPI application (1,200 LOC)
│
├── database/
│   ├── __init__.py
│   ├── models.py                 # SQLAlchemy ORM models
│   ├── session.py                # Database connection management
│   ├── schemas.py                # Pydantic validation schemas
│   └── init_db.py                # Database initialization
│
├── core/
│   ├── __init__.py
│   ├── config.py                 # Configuration management
│   ├── auth.py                   # Authentication & security
│   └── cache.py                  # Redis caching layer
│
├── tasks/
│   ├── __init__.py
│   ├── celery.py                 # Celery configuration
│   └── celery_tasks.py           # Async task definitions
│
├── modules/
│   ├── metadata_extractor.py     # EXIF extraction
│   ├── location_extractor.py     # Geolocation & reverse geocoding
│   ├── image_search.py           # Reverse image search
│   ├── maps_scraper.py           # Google Maps scraping
│   └── utils.py                  # Utility functions
│
├── app_backend.py                # Gradio frontend (API client)
├── app.py                        # Original standalone Gradio
│
├── docker-compose.yml            # Production orchestration
├── docker-compose.dev.yml        # Development orchestration
├── Dockerfile                    # API server container
├── Dockerfile.worker             # Celery worker container
│
├── .env.example                  # Environment template
├── requirements.txt              # Original dependencies
├── requirements-backend.txt      # Backend dependencies
│
├── README.md                     # This file
├── DEPLOYMENT.md                 # Production deployment guide
├── BACKEND_SETUP.md              # Architecture & setup
├── ARCHITECTURE.md               # Detailed architecture docs
│
├── uploads/                      # User uploaded images
├── outputs/                      # Analysis results & reports
└── .gitignore                    # Git ignore rules

Copy .env.example to .env and configure:

# Application
APP_NAME=ImageOSINT
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=False

# Database (choose one: sqlite, postgresql, mysql)
DATABASE_TYPE=postgresql
DATABASE_URL=postgresql://osint_user:osint_password@localhost:5432/osint_db

# Redis & Cache
REDIS_URL=redis://localhost:6379
CACHE_TTL=86400

# Celery
CELERY_BROKER=redis://localhost:6379/0
CELERY_BACKEND=redis://localhost:6379/0

# Security
JWT_SECRET=your_super_secret_key_change_in_production
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=1800

# File Upload
MAX_FILE_SIZE=104857600  # 100MB
ALLOWED_FORMATS=.jpg,.jpeg,.png,.gif,.webp

# Rate Limiting
RATE_LIMIT_DELAY=1
REQUEST_TIMEOUT=30

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:7860

# Worker Configuration
WORKERS_COUNT=4
THREADS_PER_WORKER=1

# Unit tests
pytest tests/ -v

# Coverage
pytest tests/ --cov=backend --cov=core --cov=database --cov=tasks

# Integration tests
pytest tests/integration/ -v

# API tests
pytest tests/api/ -v

Using Swagger UI:

1. Visit http://localhost:8000/api/docs
2. Click "Authorize" and enter JWT token
3. Try endpoints interactively

Using Postman:

1. Import collection: postman_collection.json
2. Set Authorization: Bearer {your_token}
3. Execute requests

http://localhost:5555
- Monitor task execution
- View task details
- Check worker status
- Analyze performance metrics

curl http://localhost:8000/health

docker exec imageosint-postgres \
  psql -U osint_user -d osint_db -c "SELECT version();"

curl http://localhost:8000/api/cache/stats

• Configure .env with production secrets
• Set up PostgreSQL database with backups
• Configure Redis for production
• Enable SSL/HTTPS
• Set up monitoring and alerts
• Configure log aggregation
• Set up automated backups
• Configure rate limiting appropriately
• Set up CI/CD pipeline
• Configure domain and DNS

# Build images
docker-compose -f docker-compose.yml build

# Start services
docker-compose -f docker-compose.yml up -d

# Verify
docker-compose ps
docker-compose logs -f api

# Create namespace
kubectl create namespace imageosint

# Deploy services
kubectl apply -f k8s/

# Verify
kubectl get all -n imageosint

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Clone repository
git clone https://github.com/QusaiALBahri/imageOSINT.git
cd imageOSINT

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dev dependencies
pip install -r requirements-backend.txt
pip install pytest pytest-cov black flake8 mypy

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Run tests
pytest tests/ -v

# Format code
black .

# Lint
flake8 .

# Type check
mypy .

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes and test thoroughly
4. Format code (black .)
5. Run tests (pytest tests/ -v)
6. Commit changes (git commit -m 'Add amazing feature')
7. Push to branch (git push origin feature/amazing-feature)
8. Open Pull Request

• FastAPI backend with 30+ endpoints
• PostgreSQL database with 7 models
• Celery async task queue
• Redis caching layer
• JWT authentication
• Docker containerization
• Gradio web interface
• Complete documentation

• GraphQL API support
• WebSocket real-time updates
• Advanced analytics dashboard
• Batch processing API
• Custom model support
• Plugin system

• Machine learning model integration
• Face detection and recognition
• Text extraction (OCR)
• Advanced image clustering
• Mobile app
• Enterprise SSO

This project is licensed under the MIT License - see LICENSE file for details.

• FastAPI: Modern Python web framework
• SQLAlchemy: Robust database ORM
• Celery: Distributed task queue
• Gradio: Easy web UI for ML models
• Redis: In-memory data store
• Docker: Container platform

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Security Policy