openosint 2.8.0

AI-powered OSINT agent, MCP server, and CLI. Interactive REPL + 11 tools. Anthropic Claude or local Ollama. For authorized security research use only.

OPENOSINT(1) — General Commands Manual

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

---

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 N]             # direct email scan, no AI
openosint username HANDLE [-t N]           # direct username scan, no AI
openosint shodan QUERY [-t N]              # Shodan lookup, no AI
openosint virustotal TARGET [-t N]         # VirusTotal lookup, no AI
openosint multi TARGETS                    # multi-target parallel investigation
openosint --parallel email ADDRESS         # parallel: search_email + search_breach
openosint --parallel username HANDLE       # parallel: search_username + search_paste
openosint --json email ADDRESS             # JSON output
openosint --provider ollama                # use local Ollama instead of Anthropic
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 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 11 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.

---

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
SHODAN_API_KEY	search_shodan	Shodan API key — get one here
VIRUSTOTAL_API_KEY	search_virustotal	VirusTotal API key — 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

---

INTERACTIVE REPL

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

openosint ❯ investigate [e-mail]

  → generate_dorks('[e-mail]')
  → search_email('[e-mail]')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_breach('[e-mail]')
  ✓ 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_email

Enumerates online services linked to an email address using holehe.

MCP parameter: email (string, required)

CLI:

$ openosint email [e-mail]
$ openosint email [e-mail] -t 60

Output:

OSINT results for '[e-mail]':
[+] 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 HIBP_API_KEY.

MCP parameter: email (string, required)

Output:

Found in 2 breach(es) for '[e-mail]':
[+] 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.

MCP parameter: domain (string, required)

Output:

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.

MCP parameter: ip (string, required)

Output:

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.

MCP parameter: domain (string, required)

Output:

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.

MCP parameter: target (string, required)

Output:

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.

MCP parameter: query (string, required)

Output:

Found in 3 paste(s) for '[e-mail]':
[+] 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.

MCP parameter: phone (string, required)

Output:

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

---

search_shodan

Queries the Shodan API. If the query is an IPv4 address, performs a host lookup (open ports, org, vulnerabilities). Otherwise performs a keyword/banner search.

MCP parameter: query (string, required) — IP address or any Shodan search query

CLI:

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

Output:

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

Requires SHODAN_API_KEY environment variable.

---

search_virustotal

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

MCP parameter: target (string, required) — IPv4 address, domain, full URL, or file hash (MD5/SHA-1/SHA-256)

CLI:

$ openosint virustotal 8.8.8.8
$ openosint virustotal example.com
$ openosint virustotal https://example.com/path
$ openosint virustotal 44d88612fea8a8f36de82e1278abb02f  # MD5 hash
$ openosint virustotal 8.8.8.8 -t 30

Output:

[VirusTotal] Type: ip
[VirusTotal] Country: US
[VirusTotal] ASN: AS15169 Google LLC
[VirusTotal] Network: 8.8.8.0/24
[VirusTotal] Malicious: 0
[VirusTotal] Suspicious: 0
[VirusTotal] Harmless: 72
[VirusTotal] Undetected: 10

If any engine flags the target as malicious:

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

Requires VIRUSTOTAL_API_KEY environment variable.

---

DIRECT CLI COMMANDS

email ADDRESS [-t SECONDS]

Enumerate services for ADDRESS via holehe. Default timeout: 120s.

username HANDLE [-t SECONDS]

Enumerate platforms for HANDLE via sherlock. Default timeout: 180s.

shodan QUERY [-t SECONDS]

Shodan host lookup (IP) or keyword search. Default timeout: 30s. Requires SHODAN_API_KEY.

virustotal TARGET [-t SECONDS]

Check an IPv4 address, domain, URL, or file hash (MD5/SHA-1/SHA-256) against VirusTotal. Auto-detects input type. Default timeout: 30s. Requires VIRUSTOTAL_API_KEY.

multi TARGETS

Investigate multiple targets in parallel. TARGETS is either a comma-separated list or a path to a file with one target per line. Maximum 10 targets. Each target gets its own report; a summary report is also generated.

Flags:

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).
--parallel	Run independent complementary tools concurrently via asyncio.gather(). For email: runs search_email + search_breach in parallel. For username: runs search_username + search_paste in parallel.
--json	Output results as structured JSON instead of formatted text.
--provider {anthropic,ollama}	AI provider for the REPL (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 alongside Markdown reports.

---

DOCKER

# Build and run
docker compose up --build

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

Set ANTHROPIC_API_KEY (and optionally HIBP_API_KEY, IPINFO_TOKEN) in a .env file or export them in your shell before running docker compose.

Reports are persisted to ./reports/ via a volume mount.

---

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 [e-mail]
openosint ❯ find all accounts for johndoe99
openosint ❯ what subdomains does example.com have?
openosint ❯ check if [phone] is a mobile number

Direct CLI:

$ openosint email [e-mail] -t 60
$ openosint username johndoe99
$ openosint -v email [e-mail]

Agentic via Claude Code:

$ claude
> Investigate [e-mail]. Trace any username found
  across other platforms and compile a full report.

---

FILES

Path	Description
openosint/agent.py	AI agent loop (Anthropic + Ollama).
openosint/repl.py	Interactive REPL session.
openosint/mcp_server.py	MCP server entry point (stdio).
openosint/cli.py	CLI entry point.
openosint/pdf_report.py	PDF report generator (reportlab).
openosint/multi_target.py	Multi-target parallel investigation.
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/search_shodan.py	Shodan host/search lookup.
openosint/tools/search_virustotal.py	VirusTotal IP/domain/URL/hash lookup.
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.
130	Terminated by SIGINT (Ctrl-C).

---

AUTHORS

Developed by Tommaso Bertocchi.

---

LICENSE

MIT License. See LICENSE.

---

OpenOSINT 2.8.0 — May 17, 2026