OpenOSINT

OpenOSINT

AI-powered OSINT agent. Interactive REPL · CLI · MCP Server · Web UI

13 tools. Powered by Anthropic Claude or local Ollama. For authorized security research only.

Legal Disclaimer: OpenOSINT is intended for legal and authorized use only. Users are solely responsible for ensuring their use complies with all applicable laws and regulations. The authors accept no liability for misuse. See DISCLAIMER.md.

What is OpenOSINT?

OpenOSINT is an AI agent for Open Source Intelligence with three interfaces: an interactive terminal REPL, a direct CLI, and an MCP server exposable to Claude Code, Claude Desktop, or any MCP-compatible client — plus a browser-based Web UI added in v2.12.0. The AI layer uses Anthropic's native tool use API (or a local Ollama model): the model issues hard stops when it needs a tool, your code executes the real binary, the actual output goes back — hallucination in tool results is structurally impossible.

Features

  • AI tool chaining — the agent decides which of 13 tools to run, chains them based on findings, and compiles a structured report
  • 13 modular tools covering email, username, breach, WHOIS, IP, subdomain, dorks, paste, phone, Shodan, VirusTotal, Censys, and IP2Location
  • Anthropic + Ollama — use Claude via API key or run fully offline with a local Ollama model
  • MCP server — expose all tools natively to Claude Code and Claude Desktop
  • Parallel execution — --parallel runs complementary tools concurrently via asyncio.gather()
  • PDF + Markdown reports — auto-saved after every investigation; PDF export via reportlab
  • Session history — all REPL sessions saved to ~/.openosint/history/; browse with openosint history
  • Web UI — browser-based AI chat with streaming output, tool cards, and light/dark theme toggle

Installation

pip install openosint

# Or install from source
git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

External binaries (must be in PATH):

Binary Purpose Install
holehe Email account enumeration pip install holehe
sherlock Username enumeration (300+ platforms) pip install sherlock-project
sublist3r Subdomain enumeration pip install sublist3r
phoneinfoga Phone number intelligence Download binary

If a binary is absent, the corresponding tool returns a descriptive error string. All other tools remain operational.

Quick Start

# Interactive AI REPL (default)
openosint

# Web interface
openosint web

# Direct tool (no AI)
openosint email [email protected]

Configuration

Store all keys in a .env file at the project root (copy .env.example). python-dotenv loads it automatically at startup.

Variable Tool Required Purpose
ANTHROPIC_API_KEY AI agent Yes (or use Ollama) Anthropic API key
HIBP_API_KEY search_breach Optional HaveIBeenPwned v3 — get one
IPINFO_TOKEN search_ip Optional ipinfo.io higher rate limits
SHODAN_API_KEY search_shodan Optional Shodan API — get one
VIRUSTOTAL_API_KEY search_virustotal Optional VirusTotal API v3 — get one
IP2LOCATION_API_KEY search_ip2location Optional IP2Location.io enhanced IP intelligence — get one (sponsored)
CENSYS_API_ID + CENSYS_SECRET search_censys Optional Censys Search API — get one

Optional Python packages:

Package Purpose Install
ollama Local LLM backend (no API key) pip install ollama
shodan Shodan API client pip install shodan
reportlab PDF report export pip install reportlab
censys Censys API client pip install censys

Tools

Tool Powered by What it investigates
search_email holehe Social accounts linked to an email address
search_username sherlock Username presence across 300+ platforms
search_breach HaveIBeenPwned v3 API Data breach exposure
search_whois python-whois Domain registrant and DNS info
search_ip ipinfo.io Geolocation, ASN, hostname
search_domain sublist3r Subdomain enumeration
generate_dorks built-in 12 targeted Google dork URLs (no network calls)
search_paste psbdmp.ws Pastebin dump mentions
search_phone phoneinfoga Carrier, country, line type
search_shodan Shodan API Open ports, banners, CVEs
search_virustotal VirusTotal API v3 Verdict from 70+ antivirus engines
search_ip2location IP2Location.io API Enhanced IP intel: VPN/Proxy/Tor/datacenter flags (sponsored)
search_censys Censys Search API Internet-facing infrastructure, certificates

search_email

Enumerates online services linked to an email address using holehe.

openosint email [email protected]
openosint email [email protected] -t 60

OSINT results for '[email protected]':
[+] Spotify        https://open.spotify.com/user/target
[+] WordPress      https://wordpress.com/target
[+] Gravatar       https://gravatar.com/target
[+] Office365      email used

search_username

Searches for a username across 300+ platforms using sherlock.

openosint username johndoe99
openosint username johndoe99 -t 120

OSINT results for username 'johndoe99':
[+] GitHub         https://github.com/johndoe99
[+] Twitter        https://twitter.com/johndoe99
[+] Reddit         https://reddit.com/user/johndoe99

search_breach

Checks data breach exposure via HaveIBeenPwned v3 API. Requires HIBP_API_KEY.

Found in 2 breach(es) for '[email protected]':
[+] LinkedIn (2016-05-05) — leaked: Email addresses, Passwords
[+] Adobe (2013-10-04) — leaked: Email addresses, Password hints

search_whois

Retrieves WHOIS data for a domain using python-whois.

WHOIS results for 'example.com':
[+] Registrar: ICANN
[+] Created: 1995-08-14
[+] Expires: 2024-08-13
[+] Name Servers: A.IANA-SERVERS.NET

search_ip

Retrieves geolocation and ASN data via ipinfo.io. Free tier: 50k/month.

IP intelligence for '8.8.8.8':
[+] Hostname: dns.google
[+] Org: AS15169 Google LLC
[+] City: Mountain View, CA, US

search_domain

Enumerates subdomains using sublist3r.

Subdomains found for 'example.com':
[+] mail.example.com
[+] dev.example.com
[+] api.example.com

generate_dorks

Generates 12 targeted Google dork URLs for any target. No network calls.

Google dork URLs for 'johndoe':
[+] "johndoe" site:linkedin.com
    https://www.google.com/search?q=%22johndoe%22+site%3Alinkedin.com
[+] "johndoe" leaked OR breach OR dump
    https://www.google.com/search?q=%22johndoe%22+leaked+OR+breach+OR+dump

search_paste

Searches Pastebin dumps via psbdmp.ws.

Found in 3 paste(s) for '[email protected]':
[+] https://pastebin.com/aB1cD2eF (2023-04-12)
[+] https://pastebin.com/xY3zA4bC (2022-11-08)

search_phone

Gathers phone intelligence using phoneinfoga. Use E.164 format.

Phone intelligence for '+14155552671':
[+] Country: United States
[+] Carrier: AT&T
[+] Line type: Mobile

search_shodan

Queries the Shodan API. IPv4 input → host lookup (open ports, org, CVEs). Any other query → banner/keyword search. Requires SHODAN_API_KEY.

openosint shodan 8.8.8.8
openosint shodan "apache port:80 country:DE"
openosint shodan 8.8.8.8 -t 30

Shodan host intelligence for '8.8.8.8':
[+] IP: 8.8.8.8
[+] Org: Google LLC
[+] Country: United States
[+] Open ports: 53, 443

search_virustotal

Checks an IP address, domain, URL, or file hash against VirusTotal's 70+ antivirus engines using API v3. Auto-detects input type. Requires VIRUSTOTAL_API_KEY.

openosint virustotal 8.8.8.8
openosint virustotal example.com
openosint virustotal https://example.com/path
openosint virustotal 44d88612fea8a8f36de82e1278abb02f

[VirusTotal] Type: ip
[VirusTotal] ASN: AS15169 Google LLC
[VirusTotal] Malicious: 0
[VirusTotal] Harmless: 72

If any engine flags the target:

[VirusTotal] Malicious: 3
FLAGGED AS MALICIOUS by 3 engines

search_censys

Queries the Censys API. IPv4 input → host view (open ports, services, ASN); domain input → certificate search (SANs, issuer, first/last seen). Requires CENSYS_API_ID and CENSYS_SECRET.

openosint censys 8.8.8.8
openosint censys example.com

[Censys] IP: 8.8.8.8
[Censys] Open Ports: 53, 443, 853
[Censys] Services: DNS, HTTPS, DNS-over-TLS
[Censys] ASN: AS15169 Google LLC
[Censys] Country: United States

[Censys] Domain: example.com
[Censys] Certificates Found: 12
[Censys] Issuer: Let's Encrypt
[Censys] SANs: example.com, www.example.com, api.example.com

search_ip2location

Queries the IP2Location.io API for enhanced IP intelligence: geolocation (country, region, city, coordinates, ZIP), ISP, domain, ASN, and — on the Security Plan — VPN, proxy, Tor exit node, and datacenter detection. Sponsored integration. Requires IP2LOCATION_API_KEY.

openosint ip2location 8.8.8.8
openosint ip2location 2001:4860:4860::8888

[IP2Location] IP: 8.8.8.8
[IP2Location] Country: United States (US)
[IP2Location] Region: California
[IP2Location] City: Mountain View
[IP2Location] ISP: Google LLC
[IP2Location] ASN: AS15169 Google LLC
[IP2Location] VPN: No  |  Proxy: No  |  TOR: No  |  Datacenter: Yes
[IP2Location] Threat: clean

If a VPN, proxy, or Tor exit node is detected:

FLAGGED: VPN/Proxy/Tor detected

Interfaces

Interactive REPL

Run openosint with no arguments to start the AI-powered REPL:

openosint > investigate [email protected]

  -> generate_dorks('[email protected]')
  -> search_email('[email protected]')
  Found: Spotify, WordPress, Gravatar, Office365

  -> search_breach('[email protected]')
  Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  Report saved -> reports/2026-05-11_14-32-11_report.md

REPL commands:

Command Description
<target> Investigate any target — email, username, domain, IP, name
clear Reset conversation memory
save Save last report to reports/
tools List available tools and their status
config Show current configuration
history Browse saved sessions
help Show all commands
exit / Ctrl-D Exit

All sessions are auto-saved to ~/.openosint/history/. Browse with openosint history.

Web UI

Introduced in v2.12.0:

openosint web
# Opens http://localhost:8080 automatically

Browser-based AI chat interface with streaming tool output, inline result cards, light/dark theme toggle, and Ollama support for fully local inference. No API key required when using Ollama.

# Install web extras
pip install "openosint[web]"
openosint web

# Use Ollama for local inference (no API key)
ollama pull llama3.2
openosint web
# Settings -> Ollama (local) -> set model to llama3.2
Web UI — launch with openosint web
OpenOSINT web UI demo

MCP Server

Expose all 13 OpenOSINT tools to any MCP-compatible AI client. Once connected, Claude can natively invoke all 13 tools during conversations.

Claude Code:

claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py
claude mcp list

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openosint": {
      "command": "python",
      "args": ["/absolute/path/to/OpenOSINT/openosint/mcp_server.py"]
    }
  }
}

Agentic use via Claude Code:

$ claude
> Investigate [email protected]. Trace any username found
  across other platforms and compile a full report.

Docker

# Build and run
docker compose up --build

# One-off command
docker compose run --rm openosint email [email protected] --json

Set ANTHROPIC_API_KEY (and optionally HIBP_API_KEY, IPINFO_TOKEN) in a .env file or export them before running docker compose. Reports are persisted to ./reports/ via a volume mount.

DigitalOcean App Platform: see .do/app.yaml for App Platform configuration.

CLI Reference

Flag / Subcommand Description
openosint Interactive AI REPL (default)
openosint web [--port N] [--no-browser] Launch browser UI
openosint email ADDRESS [-t N] Direct email scan
openosint username HANDLE [-t N] Direct username scan
openosint shodan QUERY [-t N] Shodan lookup
openosint virustotal TARGET [-t N] VirusTotal lookup
openosint censys TARGET [-t N] Censys lookup
openosint ip2location IP [-t N] IP2Location lookup
openosint multi TARGETS Parallel multi-target investigation (max 10)
openosint history [--all] [open N] [clear] View/manage REPL session history
-v, --verbose Enable debug logging to stderr
-t, --timeout N Override subprocess timeout (seconds)
--api-key KEY Anthropic API key (overrides env var)
--parallel Run complementary tools concurrently
--json Output results as structured JSON
--provider {anthropic,ollama} AI provider (default: anthropic)
--ollama-model MODEL Ollama model name (default: llama3.2)
--ollama-host URL Ollama server URL (default: http://localhost:11434)
--no-pdf Disable automatic PDF generation