Social-Hunt

Social-Hunt is an OSINT framework for cross-platform username discovery, breach exposure lookups, and avatar-based face matching. It ships with a web dashboard and a CLI, supports data-driven provider packs, and includes optional AI-powered face restoration/demasking.

Features

• Username presence scanning across many platforms using YAML providers.
• Breach intelligence via Have I Been Pwned (HIBP) and BreachVIP.
• Face matching against profile avatars using face recognition and image hashing.
• Reverse image OSINT links (Google Lens, Bing, Yandex, etc.).
• Tor/Onion site support via SOCKS proxy (split-tunneling).
• Optional AI face restoration/demasking via Replicate, IOPaint, or DeepMosaic.
• Plugin system with hot-reload and optional web uploader.
• Demo mode that censors sensitive data for safe demonstrations.
• Dashboard theme applies immediately on selection.

Tested Environments / VPS Compatibility

Known-good environments for self-hosting:

• Ubuntu 22.04 LTS (Jammy) on VPS providers (tested)

Notes:

• Other Debian/Ubuntu-based VPS images should work, but may require minor adjustments.
• If you deploy on a different OS/distro, please report your results in an issue or PR.

Architecture

• Backend: FastAPI + httpx async scanning engine.
• Frontend: Static HTML/CSS/JS dashboard (no heavy framework).
• Core engine: async concurrency with per-provider rules and status heuristics.

Quick Start

Docker (recommended)

git clone https://github.com/AfterPacket/Social-Hunt.git
cd Social-Hunt/docker
docker-compose up -d --build

Open http://localhost:8000.

Docker + bundled reverse proxy (nginx or apache)

Use a proxy profile to expose the app on port 80:

cd Social-Hunt/docker
# Nginx
docker compose --profile nginx up -d --build

# Apache
docker compose --profile apache up -d --build

Open http://localhost/.

To include IOPaint behind the same proxy:

docker compose --profile nginx --profile iopaint up -d --build

Docker + SSL (nginx + IOPaint)

This enables HTTPS termination and routes / to Social-Hunt and /iopaint to IOPaint.

cd Social-Hunt/docker
python setup_ssl.py
docker compose --profile certbot run --rm --service-ports certbot
docker compose --profile ssl up -d

Open https://your-domain.

Manual install

git clone https://github.com/AfterPacket/Social-Hunt.git
cd Social-Hunt
python -m pip install -r requirements.txt
# For Tor/SOCKS support, ensure httpx-socks is installed:
python -m pip install httpx[socks]
python run.py

Open http://localhost:8000.

For a full setup guide (virtualenv, tokens, Docker details), see README_RUN.md.

CLI Usage

python -m social_hunt.cli <username> --platforms github twitter reddit

Useful options:

• --format csv|json (default: csv)
• --max-concurrency 6
• --face-match /path/to/image1.jpg /path/to/image2.png
• --verbose (writes social_hunt.log)

Configuration

Settings file

Settings are stored in data/settings.json (or SOCIAL_HUNT_SETTINGS_PATH).

Common keys:

• admin_token (dashboard admin token; can be set via the Token page)
• hibp_api_key (required for HIBP)
• replicate_api_token (required for Replicate-based demasking)
• public_url (base URL for reverse-image links)

Settings resolution order is:

1. data/settings.json (or SOCIAL_HUNT_SETTINGS_PATH)
2. environment variables: KEY, KEY uppercased, SOCIAL_HUNT_<KEY uppercased>

Environment variables

Variable	Purpose
SOCIAL_HUNT_HOST	Bind address (default: 0.0.0.0)
SOCIAL_HUNT_PORT	Server port (default: 8000)
SOCIAL_HUNT_RELOAD	Enable auto-reload (1 for dev)
SOCIAL_HUNT_SETTINGS_PATH	Override data/settings.json
SOCIAL_HUNT_PROVIDERS_YAML	Override providers.yaml
SOCIAL_HUNT_JOBS_DIR	Override jobs output directory
SOCIAL_HUNT_PUBLIC_URL	Base URL for reverse image engines
SOCIAL_HUNT_PLUGIN_TOKEN	Admin token for protected actions
SOCIAL_HUNT_ENABLE_TOKEN_BOOTSTRAP	Allow setting admin token in UI
SOCIAL_HUNT_BOOTSTRAP_SECRET	Alternative bootstrap guard via X-Bootstrap-Secret
SOCIAL_HUNT_ENABLE_WEB_PLUGIN_UPLOAD	Allow plugin uploads in dashboard
SOCIAL_HUNT_ALLOW_PY_PLUGINS	Allow Python plugins (executes code)
SOCIAL_HUNT_PLUGIN_DIR	Upload target for web plugins (default: plugins/providers)
SOCIAL_HUNT_PLUGINS_DIR	Base plugins directory (default: plugins)
SOCIAL_HUNT_DEMO_MODE	Censor sensitive fields in results
SOCIAL_HUNT_FACE_AI_URL	External face restoration endpoint
REPLICATE_API_TOKEN	Replicate API token for demasking
SOCIAL_HUNT_PROXY	SOCKS Proxy URL for .onion/darkweb access (e.g., socks5h://127.0.0.1:9050)

Tor / Darkweb Support

Social-Hunt supports scanning .onion sites by routing traffic through a Tor proxy. It uses split-tunneling, so regular sites (like Twitter) use your direct connection while .onion sites go through the proxy. For safety, avatar face matching skips .onion hosts.

Prerequisites

1. Install Tor (e.g., sudo apt install tor or use Tor Browser).
2. Install SOCKS dependencies:

   pip install httpx[socks]

Configuration

Set the SOCIAL_HUNT_PROXY environment variable before starting the app. Use socks5h:// to ensure DNS resolution happens over Tor.

Linux/Mac:

export SOCIAL_HUNT_PROXY="socks5://127.0.0.1:9050"
python run.py

Windows:

$env:SOCIAL_HUNT_PROXY="socks5h://127.0.0.1:9150"
python run.py

(Note: Standard Tor service uses port 9050; Tor Browser usually uses 9150).

Plugins

Social-Hunt supports YAML provider packs and optional Python plugins:

• YAML providers: plugins/providers/*.yaml
• Python providers/addons: plugins/python/providers/*.py, plugins/python/addons/*.py

To enable Python plugins, set SOCIAL_HUNT_ALLOW_PY_PLUGINS=1.

The dashboard can upload .yaml or .zip bundles when:

SOCIAL_HUNT_ENABLE_WEB_PLUGIN_UPLOAD=1
SOCIAL_HUNT_PLUGIN_TOKEN=long_random_token

See PLUGINS.md for full details and plugin contracts.

Reverse Image OSINT

Reverse-image links require a public base URL for your instance:

• Set public_url in settings or SOCIAL_HUNT_PUBLIC_URL in the environment.

AI Demasking (Replicate, IOPaint, or Self-Hosted)

Social-Hunt supports multiple demasking modes:

• Replicate API models (managed SaaS).
• IOPaint WebUI for interactive inpainting.
• DeepMosaic for automated mosaic removal (image/video).

Replicate API

Set a Replicate API token in either:

• Settings: replicate_api_token
• Environment: REPLICATE_API_TOKEN

When configured, the server uses Replicate models to remove masks and restore facial detail.

IOPaint (interactive)

Use the IOPaint page in the Demasking menu to:

• Start/stop the local IOPaint server
• Open the IOPaint WebUI
• Select model/device/port

You can also host IOPaint under /iopaint behind the same domain (see APACHE_SETUP.md and NGINX_SETUP.md).

DeepMosaic (automated)

DeepMosaic can remove mosaics from images or video. Use the DeepMosaic page to:

• Upload image/video
• Choose clean/add/style modes
• Download results or save to notes

Self-hosted (custom)

Set SOCIAL_HUNT_FACE_AI_URL to an HTTP endpoint that accepts JSON:

{
  "image": "<base64 image bytes>",
  "fidelity": 0.7,
  "task": "face_restoration"
}

and returns:

{ "image": "<base64 restored image bytes>" }

The repo includes a DeepMosaics/ submodule you can use to build a local restoration service, but it does not match the /restore JSON contract out of the box. Add a small adapter or proxy to translate the request/response format, then point SOCIAL_HUNT_FACE_AI_URL at it.

Troubleshooting

• BreachVIP 403: Cloudflare may block datacenter IPs. Try manual search or change IP.
• HIBP skipped: missing or invalid hibp_api_key.
• Missing Python providers: ensure SOCIAL_HUNT_ALLOW_PY_PLUGINS=1.
• Demask not working: set REPLICATE_API_TOKEN or SOCIAL_HUNT_FACE_AI_URL.

Project Structure

• api/ FastAPI app and settings store
• social_hunt/ core engine, registry, providers, addons, CLI
• web/ static dashboard UI
• plugins/ YAML providers and optional Python plugins
• data/ settings and scan jobs
• docker/ container build/deploy files

Documentation

• README_RUN.md execution and configuration guide
• PLUGINS.md plugin formats and uploader
• APACHE_SETUP.md Apache reverse proxy notes
• NGINX_SETUP.md Nginx reverse proxy notes
• CANARY.md canary warrant template
• PGP.md PGP public key template
• NEWS_OSINT.md OSINT news digest template
• LICENSE GPL-3.0

Reverse Proxy Notes (IOPaint on same domain)

If you want IOPaint under the same domain (e.g., /iopaint), Social-Hunt's API is moved to /sh-api to avoid conflicts with IOPaint's /api and /socket.io routes. Make sure your reverse proxy routes /sh-api to the app and /api to IOPaint as shown in APACHE_SETUP.md. SUPER IMPORTANT NOTE: You must follow APACHE_SETUP.md or NGINX_SETUP.md for reverse proxy setup.

Screenshots / UI Tour

Login

Self-hosted OSINT aggregator with admin token authentication

Dashboard

Main dashboard showing welcome screen and recent job history

Username Search

Comprehensive username search across 500+ platforms with real-time status indicators

Breach Search

Data breach lookup powered by BreachVIP

Reverse Image Search

Reverse image search with multiple engine options (Google Lens, Bing, Yandex)

AI Face Restoration

Forensic AI demasking using Replicate or self-hosted models

History

Search History

Secure Notes

Encrypted notes with AES-256-GCM encryption

Master password protection for secure notes

Plugin System

YAML provider packs and plugin upload interface

Settings & Configuration

Server configuration, theme selection, and API integrations

Token Management

Admin token and browser token management

Contributors

Thanks to everyone who has helped build and maintain Social-Hunt. Add contributors here or link to a CONTRIBUTORS file if you prefer.

Legal and Ethics

Social-Hunt is for lawful, authorized investigations only. You are responsible for complying with platform terms and local laws.