Investigate public identity data with an AI agent that follows leads and documents its evidence.
Important
Use OSINT-D2 only for lawful, authorized investigations. It collects and infers information about people. Privacy law can apply even to public data, results can be wrong, and scan results are sent to your AI provider unless you use Ollama. Read Security & Responsible Use first.
OSINT-D2 is a command-line tool and local web dashboard for security researchers, journalists, and OSINT analysts. Give it a username, email, or phone number, and it checks public sources, separates likely matches from namesakes, and produces a report you can verify.
| Agent investigations | An LLM chooses which tools to run, follows new leads such as emails and websites, and writes a report. |
| Direct scans | 20 username scanners and 4 email scanners, with optional Sherlock (about 470 sites) and site lists. No AI needed. |
| False-positive filtering | Declare accounts you already trust (--trust github:johndoe). Other profiles are scored on name, bio, avatar, and location, and contradictions are discarded. |
| Identity correlation | Compares avatars with perceptual hashing and writing style with character n-grams. |
| Reports | PDF dossiers, JSON, and graphs for Obsidian Canvas and HTML. |
| Choice of AI provider | DeepSeek, OpenAI, or any OpenAI-compatible API. Use Ollama to keep inference on your machine. |
An agent run looks like this (illustrative, with fictitious data):
Target: johndoe
scan_username johndoe 3 confirmed of 20 scanned
fetch_url example.com/johndoe found [email protected]
scan_email [email protected] 2 confirmed
generate_report confidence 82% (model estimate)
Direct scans need no API key. Agent runs and AI analysis need one, unless you use Ollama.
Requires Python 3.11+ and pipx.
pipx install git+https://github.com/Doble-2/osint-d2.git
osint-d2 scan johndoeThat's enough for scans. Run osint-d2 doctor run to see which optional parts are missing, and osint-d2 serve to open the dashboard, which offers to install what it needs.
curl -fsSLO https://raw.githubusercontent.com/Doble-2/osint-d2/main/scripts/install-docker.sh
sh install-docker.shThis creates an osint-d2 folder with the Compose file, a .env for your AI key, and a reports folder. Open http://localhost:8000. To use the CLI, prefix commands with docker compose exec osint-d2:
docker compose exec osint-d2 osint-d2 scan johndoeFor development. Requires Python 3.11+ and Poetry. The Pango libraries are optional, for CLI PDFs.
git clone https://github.com/Doble-2/osint-d2.git && cd osint-d2
poetry install
poetry run playwright install chromium
cp .env.example .env # Add your AI key
poetry run osint-d2 doctor run
poetry run osint-d2 serveDownload them from Releases. They aren't signed, so your system may warn you. The installation guide explains that, and what PDFs need.
Warning
OSINT-D2 is a local tool: for ethical and legal reasons, the project doesn't operate a hosted version. The dashboard has no authentication by design and listens on localhost. Don't expose it to other people or to the internet.
# Scan a username (no AI)
osint-d2 scan johndoe
# Several targets, with Sherlock
osint-d2 hunt -u johndoe,jdoe123 -e [email protected] --sherlock
# Add AI analysis and a PDF
osint-d2 hunt -u johndoe --ai --export-pdf
# Agent investigation, starting from a trusted account
osint-d2 agent johndoe --trust github:johndoe --max-steps 10
# Machine-readable output (the default when piping)
osint-d2 scan johndoe --format json | jq '.profiles[] | select(.exists)'See the CLI reference for every option.
Set a provider and key in .env. The endpoint and model come from the provider unless you override them.
# DeepSeek (default)
OSINT_D2_AI_PROVIDER=deepseek
OSINT_D2_AI_API_KEY=sk-xxxxxxxx
# OpenAI
OSINT_D2_AI_PROVIDER=openai
OSINT_D2_AI_API_KEY=sk-xxxxxxxx
# Ollama (no key needed)
OSINT_D2_AI_PROVIDER=ollama
OSINT_D2_AI_MODEL=llama3.1Inside Docker, Ollama also needs its container address.
Optional services:
- Breach checks: set
OSINT_D2_HIBP_API_KEYto use the official Have I Been Pwned API, a paid service. It receives the full email address. - Proxy: OSINT-D2 can route scans through ScrapingAnt, a third-party service, using
OSINT_D2_PROXY_API_KEY.
| Tool | Purpose |
|---|---|
scan_username |
Check a username across the 20 native scanners |
scan_email |
Gravatar and PGP keyservers, with an optional username pivot |
breach_check |
Query the official Have I Been Pwned API (optional) |
fetch_url |
Extract emails and social links from a page, with SSRF protection |
compare_avatars |
Compare images with a perceptual hash (dHash) |
scan_phone |
Carrier, country, line type, and WhatsApp status |
search_vector_memory |
BM25 keyword search across collected evidence |
correlate_stylometry |
Compare writing style with character n-grams |
generate_report |
Finish with the report |
The report covers identity, geo-temporal signals, and technical profile. Personality (OCEAN), ideology, and attack-surface sections are off by default; enable them with --sensitive-inferences. They are speculative inferences, and the confidence score is the model's own estimate, so verify them before relying on them.
- Installation and Quick Start
- Web Dashboard and Agent Mode
- Trust Anchors and Architecture
- REST and WebSocket API
- Security & Responsible Use
See CONTRIBUTING.md and the guide to adding a scanner.
poetry install
poetry run pytest
poetry run ruff check .OSINT-D2 is intended for authorized security research, journalism, and OSINT investigations. You are responsible for complying with the laws that apply to you. The authors assume no liability for misuse.
MIT © Doble-2