DESCRIPTION

openosint is a modular OSINT framework with three interfaces:

Interactive REPL (default) — a Claude Code-style terminal where you type targets or questions in natural language. The AI agent decides which tools to run, chains them intelligently based on findings, and compiles a structured report.

Direct CLI — run individual OSINT tools without AI for scripting or quick lookups.

MCP Server — expose all 12 tools to any MCP-compatible AI client (Claude Code, Claude Desktop).

The framework is built on Python asyncio. All external binaries run as managed subprocesses with hard timeout enforcement. The AI layer uses the Anthropic native tool use API — or a local Ollama model (no API key required). When using Anthropic, the model issues hard stops when it needs a tool, your code executes it, the real output goes back. Hallucination in tool results is structurally impossible.

⭐ Support the Project

If OpenOSINT is useful to you, please consider starring the repository. Stars help the project grow and reach more developers.

ARCHITECTURE

| Layer | Path | Responsibility | |-------|------|----------------| | Core tools | openosint/tools/ | Async wrappers around external OSINT binaries and APIs. Stateless. | | AI agent | openosint/agent.py | Anthropic tool use loop. Maintains conversation history. | | REPL | openosint/repl.py | Interactive terminal session. prompt_toolkit + Rich. | | MCP server | openosint/mcp_server.py | MCP tool schema exposure for AI clients. | | CLI | openosint/cli.py | Entry point. Launches REPL or direct commands. |

No layer imports from a layer above it.

INSTALLATION

Requires Python 3.10 or later.

git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

Set your Anthropic API key (not required when using Ollama):

export ANTHROPIC_API_KEY=sk-ant-...

Optional: use a local Ollama model instead of Anthropic:

# Install Ollama from https://ollama.com, then:
ollama pull llama3.2
pip install ollama
openosint --provider ollama

External dependencies (must be present 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.

Optional environment variables:

| Variable | Tool | Purpose | |----------|------|---------| | HIBP_API_KEY | search_breach | HaveIBeenPwned API key — get one here | | IPINFO_TOKEN | search_ip | ipinfo.io token for higher rate limits | | IP2LOCATION_API_KEY | search_ip2location | IP2Location API key — get one here | | SHODAN_API_KEY | search_shodan | Shodan API key — get one here | | VIRUSTOTAL_API_KEY | search_virustotal | VirusTotal API key — get one here | | CENSYS_API_ID | search_censys | Censys API ID — get one here | | CENSYS_SECRET | search_censys | Censys API Secret — get one here |

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 |

INTERACTIVE REPL

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

openosint ❯ investigate target@example.com

  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_breach('target@example.com')
  ✓ Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  ╭──────────────────── Report ────────────────────╮
  │ ## Summary                                     │
  │ Single target identified — high confidence.    │
  │                                                │
  │ ## Online Presence                             │
  │ Spotify · WordPress · Gravatar · Office365     │
  │                                                │
  │ ## Data Breaches                               │
  │ LinkedIn (2016) · Adobe (2013)                 │
  │                                                │
  │ ## Conclusion                                  │
  │ Moderate footprint. Credential rotation        │
  │ advised given breach exposure.                 │
  ╰────────────────────────────────────────────────╯

  ✓ 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 | | help | Show all commands | | exit / Ctrl-D | Exit |

Reports are auto-saved after every investigation containing structured findings.

TOOLS

| Tool | Method | What it finds | |------|--------|---------------| | search_email | holehe | Social accounts linked to an email | | search_username | sherlock | Accounts across 300+ platforms | | search_breach | HaveIBeenPwned API | Data breach exposure | | search_whois | python-whois | Domain registrant info | | search_ip | ipinfo.io | Geolocation, ASN, hostname | | search_domain | sublist3r | Subdomain enumeration | | generate_dorks | built-in | Google dork URL generation | | 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 | Malicious/clean verdict from 70+ engines | | search_censys | Censys API | Open ports, services, certificate history | | search_ip2location | IP2Location API | Geolocation, ISP, VPN/Proxy/Tor/Datacenter detection |

search_email

Enumerates online services linked to an email address using holehe.

MCP parameter: email (string, required)

CLI:

$ openosint email target@example.com
$ openosint email target@example.com -t 60

Output:

OSINT results for 'target@example.com':
[+] 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.

MCP parameter: username (string, required)

CLI:

$ openosint username johndoe99
$ openosint username johndoe99 -t 120

Output:

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 `