Openosint— agent skill

mcp-name: io.github.OpenOSINT/openosint

<div align="center"> <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/v2.19.1/docs/logo.svg" alt="OpenOSINT" width="200" /> <h1>OpenOSINT</h1> <p><strong>AI-powered OSINT agent. Interactive REPL · CLI · MCP Server · Web UI</strong></p> <p>18 tools. Works natively with <strong>Claude Code</strong>, <strong>Claude Desktop</strong>, and any MCP-compatible client (Cursor, Windsurf, …). Powered by Anthropic Claude, local Ollama, or any OpenAI-compatible endpoint. For authorized security research only.</p> <p>New to OSINT? Start here → <a href="https://openosint.tech/learn">openosint.tech/learn</a></p> </div>

<div align="center">

See DISCLAIMER.md for legal and ethical use information.

<a href="https://opencollective.com/openosint_oss"><img src="https://opencollective.com/openosint_oss/donate/[email protected]?color=blue" alt="Donate to OpenOSINT on Open Collective" width="200" /></a>

</div>

<div align="center"> <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/v2.19.1/assets/demo.gif" alt="OpenOSINT terminal demo" width="900" /> </div>

pip install openosint

• 18 modular tools — email, username, IP, domain, WHOIS, breach, phone, paste, Shodan, VirusTotal, Censys, AbuseIPDB, GitHub, DNS, live dork search, and URL scraping
• MCP server built in — expose all 18 tools natively to Claude Code, Claude Desktop, and any MCP-compatible client; no extra config needed
• Three AI backends — Anthropic Claude (default), local Ollama, or any OpenAI-compatible endpoint; tool results come from real subprocess calls, never hallucinated
• Fully async — parallel tool execution via asyncio.gather() with hard subprocess timeouts
• MIT licensed — no embedded LLM; bring your own API key or run fully offline

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.

Sponsors

<table> <tr> <td align="center" valign="top" width="200"> <a href="https://www.ip2location.com" rel="noopener sponsored"> <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/ip2location-logo.png" alt="IP2Location — IP geolocation and threat intelligence provider" width="140"> </a><br> _{<b>IP2Location</b>}<br> _{IP Geolocation &amp; IP Intelligence}<br> _{<em>Enhanced IP geolocation, ISP, VPN/Proxy/Tor detection.</em>} </td> <td valign="top"> <b>Your logo here</b><br> _{Open: <b>proxy detection</b> · <b>breach data</b> · <b>threat intel</b> · <b>email/identity</b>}<br> _{One vendor per category — exclusive placement across README, docs, CLI, and Web UI.}<br><br> _{<a href="https://openosint.tech/sponsors.html">Media kit &amp; pricing →</a> · <a href="https://opencollective.com/openosint_oss">Open Collective</a> · <a href="mailto:[email protected]?subject=OpenOSINT%20Sponsorship%20Inquiry">[email protected]</a>} </td> </tr> </table>

Custom Integrations

Need OpenOSINT wired into your SOC, fraud, threat-intel, or AI-agent stack? I build bespoke OSINT & MCP integrations for teams — you bring the data sources and compliance requirements, I deliver a working integration.

→ [Get in touch](mailto:[email protected]?subject=OpenOSINT%20Custom%20Integration)

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, or any OpenAI-compatible endpoint): 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 18 tools to run, chains them based on findings, and compiles a structured report
• 18 modular tools covering email, username, breach, WHOIS, IP, subdomain, dorks, paste, phone, Shodan, VirusTotal, Censys, IP2Location, AbuseIPDB, GitHub, DNS, live dork search, and URL scraping
• Anthropic, Ollama, or any OpenAI-compatible endpoint — use Claude via API key, run fully offline with a local Ollama model, or point at any OpenAI-compatible server (LiteLLM, llama-swap, vLLM, LM Studio, …)
• 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

🎁 Free: 5 AI OSINT prompts (starter set)

New to AI-assisted OSINT? The free starter set gives you 5 structured prompts — one per stage of a real investigation — that make ChatGPT and Claude collect real public data instead of hallucinating it.

• Scope → Collect → Pivot → Verify → Document
• Works with any AI assistant (Claude, ChatGPT, Gemini)
• Free PDF, instant download — enter $0, no card needed

→ [Free download on Gumroad](https://tommasodev.gumroad.com/l/free-osint-prompts?utm_source=github&utm_medium=readme&utm_campaign=free_starter)

🧠 Full method — AI OSINT Prompt Pack

OpenOSINT gives you the tooling. The AI OSINT Prompt Pack gives you the method: 30+ tested prompts that make ChatGPT / Claude collect → pivot → verify against real public sources instead of hallucinating.

• Email, username, domain, IP, phone, company due-diligence, image & reporting prompts
• One repeatable investigation flow + an ethics & legal primer
• 7-page PDF · instant download · pairs directly with OpenOSINT

→ [Get the Prompt Pack ($29)](https://tommasodev.gumroad.com/l/ai-osint-prompt-pack?utm_source=github&utm_medium=readme&utm_campaign=prompt_pack)

_Buying it directly funds OpenOSINT's development. 🙏_

Installation

# Install from PyPI (recommended)
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):

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.

Optional Python packages:

Tools

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

search_abuseipdb

Checks an IP address against the AbuseIPDB v2 API for abuse reputation. Returns abuse confidence score (0–100%), total reports, country, ISP, domain, and last reported timestamp. Requires ABUSEIPDB_API_KEY.

openosint abuseipdb 198.51.100.1
openosint abuseipdb 198.51.100.1 -t 30

Abuse intelligence for '198.51.100.1':

[AbuseIPDB] IP: 198.51.100.1
[AbuseIPDB] Abuse Confidence Score: 87%
[AbuseIPDB] Total Reports: 143
[AbuseIPDB] Country: US
[AbuseIPDB] ISP: Example ISP LLC
[AbuseIPDB] Domain: example-isp.net
[AbuseIPDB] Last Reported: 2026-05-20T14:33:00+00:00
⚠️  HIGH ABUSE CONFIDENCE — flagged by AbuseIPDB

The warning line only appears when abuseConfidenceScore exceeds 50%.

search_dorks_live

Executes live Google dork queries for a target through the Bright Data SERP API¹, returning structured results (title, URL, snippet) for each dork. Reuses the same templates as generate_dorks — the offline tool remains unchanged. Each dork is a separate billable API call; defaults to 5 dorks per run. Requires BRIGHTDATA_API_KEY and BRIGHTDATA_SERP_ZONE.

openosint search-dorks-live "john doe"
openosint search-dorks-live "[email protected]" --max-dorks 3
openosint search-dorks-live example.com --max-dorks 5 -t 30

Bright Data live dork search for 'john doe' (5 queries):

[+] Dork: "john doe"
    Title:   John Doe — LinkedIn
    URL:     https://www.linkedin.com/in/johndoe
    Snippet: Software engineer with 10 years of experience...

[+] Dork: "john doe" site:linkedin.com
    Title:   John Doe | LinkedIn
    URL:     https://www.linkedin.com/in/john-doe-12345
    ...

scrape_url

Fetches any public URL through the Bright Data Web Unlocker API¹, bypassing Cloudflare, CAPTCHA, and other bot-protection mechanisms. Returns clean Markdown using the API's native data_format: "markdown" conversion. A general primitive the AI agent can chain after discovering URLs with other tools. Requires BRIGHTDATA_API_KEY and BRIGHTDATA_UNLOCKER_ZONE.

openosint scrape https://example.com
openosint scrape https://protected-site.com -t 60

[Web Unlocker] URL: https://example.com
[Web Unlocker] Remote status: 200

# Example Domain

This domain is for use in illustrative examples in documents.
You may use this domain in literature without prior coordination or asking for permission.
...

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:

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 support for fully local inference via Ollama or any OpenAI-compatible endpoint. No Anthropic API key required when using a local backend.

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

# Use Ollama for fully local inference (no API key)
# Step 1: install the Ollama runtime (separate from the Python library)
#   macOS/Linux:  curl -fsSL https://ollama.com/install.sh | sh
#   Windows:      https://ollama.com/download/windows
# Step 2: start Ollama and pull a model
ollama serve          # start in a terminal (runs automatically as a service on some platforms)
ollama pull llama3.2  # download the model (~2 GB)
# Step 3: launch OpenOSINT and switch to Ollama
openosint web
# Settings -> Ollama (local) -> set model to llama3.2

# Or point at any OpenAI-compatible endpoint (LiteLLM, llama-swap, vLLM, LM Studio, …).
# The selected model must support tool/function calling.
export OPENAI_BASE_URL="http://localhost:4000/v1"
export OPENAI_API_KEY="sk-..."        # optional for local servers
export OPENAI_MODEL="gpt-4o-mini"
openosint web
# Settings -> OpenAI API  (or just start chatting — it is auto-selected when no ANTHROPIC_API_KEY is set)

For the REPL/CLI, the same backend is available via --provider openai:

pip install "openosint[openai]"
openosint --provider openai \
  --openai-base-url http://localhost:4000/v1 \
  --openai-model gpt-4o-mini

<div align="center"> <strong>Web UI</strong> — launch with <code>openosint web</code> </div>

Live Documentation

The interactive documentation at openosint.tech covers every tool, CLI flag, and configuration option.

<div align="center"> <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/v2.19.1/assets/demo-web.gif" alt="openosint.tech documentation tour" width="900" /> </div>

MCP Server

Expose all 18 OpenOSINT tools to any MCP-compatible AI client. Once connected, Claude can natively invoke all 18 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

Integrations

Resources

• [Free AI OSINT Prompt Starter Set](https://tommasodev.gumroad.com/l/free-osint-prompts?utm_source=github&utm_medium=readme_resources&utm_campaign=free_starter) — 5 structured prompts (free PDF) to run your first AI investigation properly.
• [AI OSINT Prompt Pack ($29)](https://tommasodev.gumroad.com/l/ai-osint-prompt-pack?utm_source=github&utm_medium=readme_resources&utm_campaign=prompt_pack) — 30+ ready-to-use prompts for faster, ethical OSINT investigations with any AI assistant. Built to pair with OpenOSINT.

Sponsor this project

OpenOSINT is used by OSINT practitioners, security researchers, and developers actively evaluating intelligence APIs. Every time a user configures an integration, the docs route them to that provider's sign-up page — high-intent exposure at the moment of adoption.

Featured Integration ($2,000/year or $220/month): recommended/default provider for one tool category, exclusive. Logo + badge across README, docs, CLI banner, and Web UI. One vendor per category.

Open categories: proxy detection · breach/credential data · threat & domain intel · email/identity lookup

→ Full media kit and pricing: openosint.tech/sponsors.html

Current sponsors

<!-- SPONSORS:START -->

<a href="https://www.ip2location.io/?utm_source=openosint&utm_medium=readme&utm_campaign=featured" rel="noopener sponsored"> <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/ip2location-logo.png" alt="IP2Location" width="140"> </a>

[IP2Location.io](https://www.ip2location.io/?utm_source=openosint&utm_medium=readme&utm_campaign=featured) — Featured Integration · IP Geolocation & IP Intelligence

Enhanced IP geolocation, ISP, VPN/Proxy/Tor, and datacenter detection. Powers search_ip2location.

<!-- SPONSORS:END -->

Open Collective · [email protected] · SPONSORSHIP.md

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow, integration registration checklist, and coding conventions. Please read DISCLAIMER.md before contributing.

Maintainer

Tommaso Bertocchi

• X (personal): https://x.com/SonoTommy_
• X (OpenOSINT): https://x.com/openosint_oss
• LinkedIn: https://www.linkedin.com/company/openosintoss
• Email: [email protected]

Contributors

SERVICES

The framework is free and MIT-licensed. This is an optional paid setup service offered by the maintainer.

OSINT-MCP Setup Sprint — done-for-you installation and configuration of an autonomous OSINT-MCP pipeline on your environment. Fully async, no calls required.

Includes:

• Pre-configured OpenOSINT setup tailored to your stack (Claude Code, Claude Desktop, or any MCP client)
• API keys wired in (Shodan, VirusTotal, IP2Location, HaveIBeenPwned, and others as needed)
• One investigation workflow built around your use case
• Written step-by-step setup guide + screen-recorded walkthrough
• 1-page runbook
• Async email support for 7 days

Delivery: 3–5 days, fully async.

For: SOC analysts · threat-intel teams · fraud/AML · pentesters · OSINT investigators

Founding pricing available for early teams — inquire.

→ Email [email protected] · LinkedIn · <!-- INTAKE_FORM_LINK -->

For authorized use only. See [DISCLAIMER.md](DISCLAIMER.md).

License

OpenOSINT is open source under the MIT License — free for personal, academic, and open source use.

For commercial use in closed-source products, a separate license is required. → Full details

¹ Bright Data links in this README are affiliate/referral links — OpenOSINT earns a commission if you sign up through them, at no extra cost to you.

For authorized security research only. See [DISCLAIMER.md](DISCLAIMER.md).

OpenOSINT v2.22.0 — June 2026

Star History