openosint(1)

NAME

openosint — AI-powered OSINT agent, MCP server, and CLI for Open Source Intelligence

SYNOPSIS

openosint                          # interactive AI REPL (default)
openosint shell                    # same as above
openosint email address [-t seconds]  # direct scan, no AI
openosint username handle [-t seconds] # direct scan, no AI
openosint [-v] [--api-key key]

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 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 9 tools to any MCP-compatible AI client (Claude Code, Claude Desktop).

The AI layer uses the Anthropic native tool use API. The model issues hard stops when it needs a tool — the real tool executes and real output goes back. Hallucination in tool results is structurally impossible.

DEMO

Interactive REPL session — email investigation with breach check and username tracing.

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 per session.
REPL	`openosint/repl.py`	Interactive terminal session. prompt_toolkit + Rich.
MCP server	`openosint/mcp_server.py`	MCP tool schema exposure for external 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 .
$ export ANTHROPIC_API_KEY=sk-ant-...

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. 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

INTERACTIVE REPL

Run openosint with no arguments to start the AI-powered REPL. Type targets or questions in natural language.

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 — high confidence.       │
  │                                        │
  │ ## Online Presence                     │
  │ Spotify · WordPress · Gravatar         │
  │                                        │
  │ ## Data Breaches                       │
  │ LinkedIn (2016) · Adobe (2013)         │
  ╰────────────────────────────────────────╯

  ✓ Report saved → reports/2026-05-11_report.md

REPL commands:

Command	Description
`<target>`	Investigate any target — email, username, domain, IP, or 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

Quick reference:

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 and leaked data
`search_whois`	python-whois	Domain registrant, registrar, dates
`search_ip`	ipinfo.io	Geolocation, ASN, hostname
`search_domain`	sublist3r	Subdomain enumeration
`generate_dorks`	built-in	12 targeted Google dork URLs
`search_paste`	psbdmp.ws	Pastebin dump mentions
`search_phone`	phoneinfoga	Carrier, country, line type

search_email

Enumerates online services linked to an email using holehe.

MCP parameter: email (string, required)

$ openosint email target@example.com -t 60

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 300+ platforms using sherlock.

MCP parameter: username (string, required)

$ openosint username johndoe99

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.

MCP parameter: email (string, required)

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

search_whois

Retrieves WHOIS registration data via python-whois.

MCP parameter: domain (string, required)

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

search_ip

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

MCP parameter: ip (string, required)

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

search_domain

Enumerates subdomains via sublist3r.

MCP parameter: domain (string, required)

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

generate_dorks

Generates 12 targeted Google dork URLs. No network calls required.

MCP parameter: target (string, required)

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

search_paste

Searches Pastebin dumps via psbdmp.ws.

MCP parameter: query (string, required)

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

search_phone

Phone intelligence via phoneinfoga. Use E.164 format.

MCP parameter: phone (string, required)

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

DIRECT CLI COMMANDS

email ADDRESS [-t SECONDS] — Enumerate services via holehe. Default timeout: 120s.

username HANDLE [-t SECONDS] — Enumerate platforms via sherlock. Default timeout: 180s.

Flag	Description
`-v, --verbose`	Enable debug logging to stderr.
`-t, --timeout N`	Override subprocess timeout (seconds).
`--api-key KEY`	Anthropic API key (overrides env var).

MCP SERVER CONFIGURATION

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"]
    }
  }
}

EXAMPLES

Interactive REPL:

$ openosint
openosint ❯ investigate target@example.com
openosint ❯ find all accounts for johndoe99
openosint ❯ what subdomains does example.com have?
openosint ❯ check if +14155552671 is mobile

Direct CLI:

$ openosint email target@example.com -t 60
$ openosint username johndoe99
$ openosint -v email target@example.com

Agentic via Claude Code:

$ claude
> Investigate target@example.com. Trace any username found
  across other platforms and compile a full report.

FILES

Path	Description
`openosint/agent.py`	AI agent loop (Anthropic tool use).
`openosint/repl.py`	Interactive REPL session.
`openosint/mcp_server.py`	MCP server entry point (stdio).
`openosint/cli.py`	CLI entry point.
`openosint/tools/search_email.py`	Email enumeration.
`openosint/tools/search_username.py`	Username enumeration.
`openosint/tools/search_breach.py`	Data breach check.
`openosint/tools/search_whois.py`	WHOIS lookup.
`openosint/tools/search_ip.py`	IP intelligence.
`openosint/tools/search_domain.py`	Subdomain enumeration.
`openosint/tools/generate_dorks.py`	Google dork generator.
`openosint/tools/search_paste.py`	Pastebin search.
`openosint/tools/search_phone.py`	Phone intelligence.
`openosint/tools/exceptions.py`	Shared exception hierarchy.
`pyproject.toml`	Build configuration (PEP 621).
`DISCLAIMER.md`	Legal notice and ethical use policy.

EXIT STATUS

Code	Meaning
0	Successful execution.
1	General error (invalid arguments, tool failure).
130	Terminated by SIGINT (Ctrl-C).

LEGAL & ETHICS

openosint is for authorised security research, penetration testing, and investigative journalism only. Users are solely responsible for compliance with applicable law including GDPR, CCPA, and the Computer Fraud and Abuse Act.

Permitted	Prohibited
Authorised penetration testing	Stalking or harassment
Investigating your own accounts	Doxxing or targeted exposure
Journalistic investigation	Unauthorised surveillance
Law enforcement with legal basis	Identity theft or fraud

See DISCLAIMER.md for the full legal notice.

LICENSE

Released under the MIT License. See LICENSE in the source distribution.

GITHUB

Source code, issues, and contributions: github.com/OpenOSINT/OpenOSINT

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

Pull requests welcome. See DISCLAIMER.md before contributing.