Metadata-Version: 2.4
Name: openosint
Version: 2.25.0
Summary: AI-powered OSINT agent, MCP server, and CLI. Interactive REPL + 16 tools. Anthropic Claude or local Ollama. For authorized security research use only.
Author: Tommaso Bertocchi
License-Expression: MIT
Project-URL: Homepage, https://openosint.github.io/OpenOSINT
Project-URL: Repository, https://github.com/OpenOSINT/OpenOSINT
Project-URL: Documentation, https://openosint.github.io/OpenOSINT
Project-URL: Bug Tracker, https://github.com/OpenOSINT/OpenOSINT/issues
Keywords: osint,security,mcp,cli,ai,agent,anthropic,claude,investigation,recon,cybersecurity
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Topic :: Internet
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-whois>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: dnspython>=2.6.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: sse-starlette>=1.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0
Requires-Dist: authlib>=1.3.0
Requires-Dist: itsdangerous>=2.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-freezegun>=0.4.2; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: shodan
Requires-Dist: shodan>=1.31.0; extra == "shodan"
Provides-Extra: ollama
Requires-Dist: ollama>=0.3.0; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.40.0; extra == "openai"
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0.0; extra == "pdf"
Provides-Extra: censys
Requires-Dist: censys>=2.2.0; extra == "censys"
Provides-Extra: socks
Requires-Dist: PySocks>=1.7.1; extra == "socks"
Requires-Dist: aiohttp-socks>=0.8.4; extra == "socks"
Provides-Extra: web
Requires-Dist: fastapi>=0.110.0; extra == "web"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "web"
Requires-Dist: sse-starlette>=1.8.0; extra == "web"
Requires-Dist: python-dotenv>=1.0.0; extra == "web"
Requires-Dist: anthropic>=0.25.0; extra == "web"
Requires-Dist: playwright>=1.40.0; extra == "web"
Provides-Extra: all
Requires-Dist: shodan>=1.31.0; extra == "all"
Requires-Dist: ollama>=0.3.0; extra == "all"
Requires-Dist: openai>=1.40.0; extra == "all"
Requires-Dist: reportlab>=4.0.0; extra == "all"
Requires-Dist: censys>=2.2.0; extra == "all"
Requires-Dist: fastapi>=0.110.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "all"
Requires-Dist: sse-starlette>=1.8.0; extra == "all"
Requires-Dist: PySocks>=1.7.1; extra == "all"
Requires-Dist: aiohttp-socks>=0.8.4; extra == "all"
Dynamic: license-file

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>OSINT agent for security researchers and analysts: 18 investigation tools behind a natural-language interface.</p>
  <p>Use it as a REPL, CLI, MCP server, or browser Web UI.</p>
  <p><em>The AI issues hard-stop tool calls; your code executes the real binary — hallucinated findings are structurally impossible.</em></p>
</div>

<div align="center">

[![Release](https://img.shields.io/github/v/release/OpenOSINT/OpenOSINT?style=flat-square)](https://github.com/OpenOSINT/OpenOSINT/releases)
[![PyPI](https://img.shields.io/pypi/v/openosint?style=flat-square)](https://pypi.org/project/openosint/)
[![PyPI downloads](https://img.shields.io/pypi/dm/openosint?style=flat-square&label=PyPI%20downloads)](https://pypi.org/project/openosint/)
[![License MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/OpenOSINT/OpenOSINT?style=flat-square)](https://github.com/OpenOSINT/OpenOSINT/stargazers)
[![MCP](https://img.shields.io/badge/protocol-MCP-blueviolet?style=flat-square)](https://modelcontextprotocol.io/)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-published-blueviolet?style=flat-square)](https://registry.modelcontextprotocol.io/servers/io.github.OpenOSINT/openosint)
[![Sponsored by IP2Location](https://img.shields.io/badge/sponsored%20by-IP2Location.io-FF6B35?style=flat-square)](https://www.ip2location.io)
[![Sponsored by RapidProxy](https://img.shields.io/badge/sponsored%20by-RapidProxy-F2622B?style=flat-square)](https://www.rapidproxy.io/?ref=openosint)

</div>

<div align="center">

[![▶ Try the live demo](https://img.shields.io/badge/%E2%96%B6%20Try%20the%20live%20demo-demo.openosint.tech-brightgreen?style=for-the-badge)](https://demo.openosint.tech)

*Run a real OSINT investigation in your browser — bring your own Anthropic / OpenRouter / Ollama key, no signup.*

</div>

<div align="center">
  <a href="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/demo-web-graph.mp4">
    <img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/demo-web-graph.gif"
         alt="OpenOSINT Web UI — live entity correlation graph demo: investigating openosint.tech"
         width="900" />
  </a>
  <p><a href="https://demo.openosint.tech">Try the live demo →</a></p>
</div>

```bash
pip install openosint
```

## Quick Start

```bash
# Interactive AI REPL (default)
openosint

# Web interface
openosint web

# Direct tool (no AI)
openosint email target@example.com
```

## Usage

Start the REPL and investigate any target — the agent decides which tools to run and chains them on findings:

```text
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)

  -> search_username('johndoe99')   <- pivoted from email findings
  Found: GitHub, Reddit, Twitter

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

## Features

| Capability | Details |
|---|---|
| AI tool chaining | The agent selects and chains tools based on findings; describe the target in plain language |
| 18 modular tools | Email, username, breach, WHOIS, IP, subdomain, dorks, paste, phone, Shodan, VirusTotal, Censys, IP2Location, AbuseIPDB, GitHub, DNS, live dork search, URL scraping |
| Three AI backends | Anthropic Claude (default), local Ollama, or any OpenAI-compatible endpoint (LiteLLM, vLLM, LM Studio, ...) |
| Native MCP server | All 18 tools exposed to Claude Code, Claude Desktop, and any MCP-compatible client — no extra config |
| Parallel execution | `--parallel` runs complementary tools concurrently via `asyncio.gather()` |
| Reports | PDF + Markdown auto-saved after every investigation (`reportlab` optional) |
| Session history | All REPL sessions saved to `~/.openosint/history/`; browse with `openosint history` |
| Web UI | Browser-based AI chat with streaming output, tool cards, light/dark theme |

---

> **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](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>
<sub><b>IP2Location</b></sub><br>
<sub>IP Geolocation &amp; IP Intelligence</sub><br>
<sub><em>Enhanced IP geolocation, ISP, VPN/Proxy/Tor detection.</em></sub>
</td>
<td align="center" valign="top" width="200">
<a href="https://www.rapidproxy.io/?ref=openosint" rel="noopener sponsored">
<img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/rapidproxy-logo.svg" alt="RapidProxy — residential proxy provider" width="140">
</a><br>
<sub><b>RapidProxy</b></sub><br>
<sub>Residential Proxies</sub><br>
<sub><em>90M+ rotating residential IPs across 200+ countries — smart rotation & geo-targeting.</em></sub>
</td>
<td valign="top">
<b>Your logo here</b><br>
<sub>Open: <b>proxy detection</b> · <b>breach data</b> · <b>threat intel</b> · <b>email/identity</b></sub><br>
<sub>One vendor per category — exclusive placement across README, docs, CLI, and Web UI.</sub><br><br>
<sub><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:openosint@yahoo.com?subject=OpenOSINT%20Sponsorship%20Inquiry">openosint@yahoo.com</a></sub>
</td>
</tr>
</table>

**Reliable Residential Proxies for Data Collection & Automation**

**Access 90M+ real residential IPs across 200+ countries with smart rotation, geo-targeting, high-concurrency support, and non-expiring traffic.**

**Use Cases:** Web Scraping · Data Collection · AI Automation · Developer Tools

🎁 10% discount with code **RAPID10** → [Start Free Testing](https://www.rapidproxy.io/?ref=openosint)

## 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:openosint@yahoo.com?subject=OpenOSINT%20Custom%20Integration)**

---

## 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_abuseipdb` | AbuseIPDB v2 API | IP abuse reputation: confidence score, reports, country, ISP |
| `search_github` | GitHub REST API | Profile, repos, commit-discovered emails, username/keyword search |
| `search_dns` | dnspython (built-in) | A/AAAA/MX/NS/TXT/CNAME/SOA records; SPF, DMARC, DKIM analysis |
| `search_dorks_live` | Bright Data SERP API | Live Google search results for dork queries (title, URL, snippet) |
| `scrape_url` | Bright Data Web Unlocker | Fetch any URL bypassing Cloudflare/CAPTCHA — returns clean Markdown |

Full per-tool documentation, CLI flags, and output formats: [openosint.tech](https://openosint.tech/).

### search_email

Enumerates online services linked to an email address using [holehe](https://github.com/megadose/holehe).

```bash
openosint email target@example.com
```

```text
[+] 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](https://github.com/sherlock-project/sherlock).

```bash
openosint username johndoe99
```

```text
[+] 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](https://haveibeenpwned.com/API/v3). Requires `HIBP_API_KEY`.

```text
[+] LinkedIn (2016-05-05) — leaked: Email addresses, Passwords
[+] Adobe (2013-10-04) — leaked: Email addresses, Password hints
```

### search_whois

Retrieves WHOIS data using [python-whois](https://github.com/richardpenman/whois).

```text
[+] 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](https://ipinfo.io). Free tier: 50k/month.

```text
[+] Hostname: dns.google
[+] Org: AS15169 Google LLC
[+] City: Mountain View, CA, US
```

### search_domain

Enumerates subdomains using [sublist3r](https://github.com/aboul3la/Sublist3r).

```text
[+] mail.example.com
[+] dev.example.com
[+] api.example.com
```

### generate_dorks

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

```text
[+] "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](https://psbdmp.ws).

```text
[+] https://pastebin.com/aB1cD2eF (2023-04-12)
[+] https://pastebin.com/xY3zA4bC (2022-11-08)
```

### search_phone

Gathers phone intelligence using [phoneinfoga](https://github.com/sundowndev/phoneinfoga). Use E.164 format.

```text
[+] Country: United States
[+] Carrier: AT&T
[+] Line type: Mobile
```

### search_shodan

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

```bash
openosint shodan 8.8.8.8
openosint shodan "apache port:80 country:DE"
```

```text
[+] Org: Google LLC  |  Open ports: 53, 443
```

### search_virustotal

Checks an IP, domain, URL, or file hash against [VirusTotal](https://www.virustotal.com)'s 70+ engines. Auto-detects input type. Requires `VIRUSTOTAL_API_KEY`.

```bash
openosint virustotal 8.8.8.8
openosint virustotal example.com
openosint virustotal 44d88612fea8a8f36de82e1278abb02f
```

```text
[VirusTotal] Malicious: 0 / Harmless: 72
```

### search_ip2location

Queries [IP2Location.io](https://www.ip2location.io) for enhanced IP intelligence: geolocation, ISP, ASN, and — on the Security Plan — VPN/Proxy/Tor/datacenter detection. Sponsored integration. Requires `IP2LOCATION_API_KEY`.

```bash
openosint ip2location 8.8.8.8
```

```text
[IP2Location] City: Mountain View, CA, US  |  ISP: Google LLC
[IP2Location] VPN: No  |  Proxy: No  |  TOR: No  |  Datacenter: Yes
```

### search_censys

IPv4 → host view (open ports, services, ASN). Domain → certificate search (SANs, issuer). Requires `CENSYS_API_ID` and `CENSYS_SECRET`.

```bash
openosint censys 8.8.8.8
openosint censys example.com
```

```text
[Censys] Open Ports: 53, 443, 853  |  ASN: AS15169 Google LLC
```

### search_abuseipdb

Checks an IP against [AbuseIPDB](https://www.abuseipdb.com) v2. Returns abuse confidence score, total reports, country, ISP, and last reported timestamp. Requires `ABUSEIPDB_API_KEY`.

```bash
openosint abuseipdb 198.51.100.1
```

```text
[AbuseIPDB] Abuse Confidence Score: 87%  |  Total Reports: 143
⚠️  HIGH ABUSE CONFIDENCE — flagged by AbuseIPDB
```

Warning appears when `abuseConfidenceScore` exceeds 50%.

### search_github

Queries [GitHub REST API](https://docs.github.com/en/rest). Username → profile, repos, commit-discovered emails. Keyword → user/repo search. Optional `GITHUB_TOKEN` raises rate limit from 60 to 5000 req/h.

```bash
openosint github johndoe99
```

```text
[GitHub] Repos: 42  |  Followers: 128
[GitHub] Commit email: johndoe@example.com
```

### search_dns

Queries A/AAAA/MX/NS/TXT/CNAME/SOA records and analyzes SPF, DMARC, and DKIM configuration using [dnspython](https://www.dnspython.org) (no external API).

```bash
openosint dns example.com
```

```text
[DNS] A: 93.184.216.34
[DNS] MX: mail.example.com (priority 10)
[DNS] SPF: v=spf1 include:_spf.google.com ~all
```

### search_dorks_live

Executes live Google dork queries through the [Bright Data SERP API](https://get.brightdata.com/984ni58s2oad?utm_source=github&utm_medium=readme)¹, returning structured results (title, URL, snippet). Defaults to 5 dorks per run; each is a separate billable API call. Requires `BRIGHTDATA_API_KEY` and `BRIGHTDATA_SERP_ZONE`.

```bash
openosint search-dorks-live "john doe" --max-dorks 3
```

```text
[+] 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 [Bright Data Web Unlocker](https://get.brightdata.com/984ni58s2oad?utm_source=github&utm_medium=readme)¹, bypassing Cloudflare/CAPTCHA. Returns clean Markdown. Requires `BRIGHTDATA_API_KEY` and `BRIGHTDATA_UNLOCKER_ZONE`.

```bash
openosint scrape https://example.com
```

```text
[Web Unlocker] Remote status: 200
# Example Domain
This domain is for use in illustrative examples in documents.
```

---

## Interfaces

### Web UI

```bash
pip install "openosint[web]"
openosint web
# Opens http://localhost:8080 automatically
```

Browser-based AI chat with streaming tool output, inline result cards, light/dark theme toggle. Supports local inference via Ollama or any OpenAI-compatible endpoint — no Anthropic API key required.

```bash
# Fully local (no API key) — requires Ollama runtime: https://ollama.com
ollama pull llama3.2
openosint web
# Settings -> Ollama (local) -> model: llama3.2

# OpenAI-compatible endpoint (LiteLLM, vLLM, LM Studio, ...)
export OPENAI_BASE_URL="http://localhost:4000/v1"
openosint web
# Settings -> OpenAI API
```

### Interactive REPL

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

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

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

For the REPL/CLI with an OpenAI-compatible backend:

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

### Live Documentation

Full per-tool reference, CLI flags, and configuration options at [openosint.tech](https://openosint.tech/).

<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:**

```bash
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`:

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

**Agentic use via Claude Code:**

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

---

## Installation

```bash
# From PyPI (recommended)
pip install openosint

# 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](https://github.com/sundowndev/phoneinfoga/releases) |

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

**Optional Python packages:**

| Package | Purpose | Install |
|---------|---------|---------|
| `ollama` | Local LLM backend (no API key) | `pip install ollama` *(also requires [Ollama runtime](https://ollama.com))* |
| `openai` | OpenAI-compatible backend | `pip install "openosint[openai]"` |
| `shodan` | Shodan API client | `pip install shodan` |
| `reportlab` | PDF report export | `pip install reportlab` |
| `censys` | Censys API client | `pip install censys` |

## Configuration

Store 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 Ollama / OpenAI) | Anthropic API key |
| `OPENAI_BASE_URL` | AI agent | Optional | Base URL of an OpenAI-compatible endpoint (e.g. `http://localhost:4000/v1`) |
| `OPENAI_API_KEY` | AI agent | Optional | API key for the endpoint (local servers may ignore it) |
| `OPENAI_MODEL` | AI agent | Optional | Model name to request (default: `gpt-4o-mini`) |
| `HIBP_API_KEY` | `search_breach` | Optional | HaveIBeenPwned v3 — [get one](https://haveibeenpwned.com/API/Key) |
| `IPINFO_TOKEN` | `search_ip` | Optional | ipinfo.io higher rate limits |
| `SHODAN_API_KEY` | `search_shodan` | Optional | Shodan API — [get one](https://account.shodan.io) |
| `VIRUSTOTAL_API_KEY` | `search_virustotal` | Optional | VirusTotal API v3 — [get one](https://www.virustotal.com/gui/my-apikey) |
| `IP2LOCATION_API_KEY` | `search_ip2location` | Optional | IP2Location.io — [get one](https://www.ip2location.io/pricing) *(sponsored)* |
| `CENSYS_API_ID` + `CENSYS_SECRET` | `search_censys` | Optional | Censys — [get one](https://censys.io/account) |
| `ABUSEIPDB_API_KEY` | `search_abuseipdb` | Optional | AbuseIPDB v2 — [get one](https://www.abuseipdb.com/account/api) |
| `GITHUB_TOKEN` | `search_github` | Optional | GitHub API — raises rate limit 60 → 5000 req/h — [get one](https://github.com/settings/tokens) |
| `BRIGHTDATA_API_KEY` | `search_dorks_live`, `scrape_url` | Optional | Bright Data — [get one](https://get.brightdata.com/984ni58s2oad?utm_source=github&utm_medium=readme)¹ (free tier: 5,000 req/month) |
| `BRIGHTDATA_SERP_ZONE` | `search_dorks_live` | Optional | Your Bright Data SERP zone name (e.g. `serp_api1`) |
| `BRIGHTDATA_UNLOCKER_ZONE` | `scrape_url` | Optional | Your Bright Data Web Unlocker zone name (e.g. `web_unlocker1`) |

## 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 abuseipdb IP [-t N]` | AbuseIPDB reputation check |
| `openosint github QUERY [-t N]` | GitHub profile/repo/email discovery |
| `openosint dns DOMAIN [-t N]` | DNS records + email security analysis |
| `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,openai}` | AI provider (default: `anthropic`) |
| `--ollama-model MODEL` | Ollama model name (default: `llama3.2`) |
| `--ollama-host URL` | Ollama server URL (default: `http://localhost:11434`) |
| `--openai-base-url URL` | OpenAI-compatible endpoint base URL (env: `OPENAI_BASE_URL`) |
| `--openai-model MODEL` | Model to request from the endpoint (default: `gpt-4o-mini`; env: `OPENAI_MODEL`) |
| `--openai-api-key KEY` | API key for the endpoint (env: `OPENAI_API_KEY`) |
| `--no-pdf` | Disable automatic PDF generation |

## Docker

```bash
# Build and run
docker compose up --build

# One-off command
docker compose run --rm openosint email target@example.com --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`](.do/app.yaml) for App Platform configuration.

## Integrations

| Service | URL | Tool | Tier | Auth |
|---------|-----|------|------|------|
| IP2Location.io | https://www.ip2location.io | `search_ip2location` | Featured (sponsored) | API key — free tier |
| RapidProxy | https://www.rapidproxy.io/?ref=openosint | — | Featured (sponsored) | — |
| AbuseIPDB | https://www.abuseipdb.com | `search_abuseipdb` | Community | API key — free tier |
| Censys | https://censys.io | `search_censys` | Community | API key — free tier |
| GitHub | https://github.com | `search_github` | Community | Token optional |
| HaveIBeenPwned | https://haveibeenpwned.com | `search_breach` | Community | API key — paid |
| holehe | https://github.com/megadose/holehe | `search_email` | Community | None — local binary |
| ipinfo.io | https://ipinfo.io | `search_ip` | Community | Token optional |
| phoneinfoga | https://github.com/sundowndev/phoneinfoga | `search_phone` | Community | None — local binary |
| psbdmp.ws | https://psbdmp.ws | `search_paste` | Community | None |
| sherlock | https://github.com/sherlock-project/sherlock | `search_username` | Community | None — local binary |
| Shodan | https://shodan.io | `search_shodan` | Community | API key — free tier |
| sublist3r | https://github.com/aboul3la/Sublist3r | `search_domain` | Community | None — local binary |
| VirusTotal | https://www.virustotal.com | `search_virustotal` | Community | API key — free tier |
| WHOIS (IANA) | https://www.iana.org/whois | `search_whois` | Community | None |
| DNS (system resolver) | — | `search_dns` | Community | None |
| Google Search | https://www.google.com | `generate_dorks` | Community | None |

## Learn the Method

OpenOSINT is the tool. The **AI OSINT Operator's Playbook** (paid guide, $39) is the method — step-by-step workflows for running investigations with ChatGPT, Claude, and OpenOSINT.

**→ [Get the Playbook](https://tommasodev.gumroad.com/l/ai-osint-playbook?utm_source=github&utm_medium=readme&utm_campaign=operator_playbook)**

## Resources

### Free 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)**

### 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)**

Also available: [AI OSINT Operator's Playbook](https://tommasodev.gumroad.com/l/ai-osint-playbook?utm_source=github&utm_medium=readme&utm_campaign=operator_playbook) — paid guide, $39, covering full investigation workflows.

_Buying it directly funds OpenOSINT's development._

## 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](https://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`.

<a href="https://www.rapidproxy.io/?ref=openosint" rel="noopener sponsored">
<img src="https://raw.githubusercontent.com/OpenOSINT/OpenOSINT/main/docs/assets/rapidproxy-logo.svg" alt="RapidProxy" width="140">
</a>

**[RapidProxy](https://www.rapidproxy.io/?ref=openosint)** — Featured Integration · Residential Proxies

<!-- SPONSORS:END -->

[Open Collective](https://opencollective.com/openosint_oss) · [openosint@yahoo.com](mailto:openosint@yahoo.com?subject=OpenOSINT%20Sponsorship%20Inquiry) · [SPONSORSHIP.md](SPONSORSHIP.md)

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

**Delivery:** 3–5 days, fully async.

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

### Need it set up for you?

Get OpenOSINT wired into your stack in 3–5 days — done-for-you, fully async, no calls.

**[Book the Setup Sprint → $350 (founding price, first 5 teams)](https://tommasodev.gumroad.com/l/osint-mcp-setup-sprint)**

→ Or email [openosint@yahoo.com](mailto:openosint@yahoo.com) · [LinkedIn](https://www.linkedin.com/company/openosintoss)

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

## Commercial License & Support

OpenOSINT is free and MIT-licensed for everyone — personal projects, commercial products, SaaS, and closed-source are all covered with no purchase required. Organizations that additionally need a vendor contract, written warranty, indemnification, SLA, or priority support for procurement and compliance can purchase a commercial plan. Three tiers available from €300/year — see [COMMERCIAL.md](./COMMERCIAL.md) for full details and pricing. Contact: [commercial@openosint.tech](mailto:commercial@openosint.tech?subject=OpenOSINT%20Commercial%20Plan%20Inquiry).

## Contributing

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

### Regenerating the demo GIF/MP4

```bash
export OPENOSINT_DEMO_KEY=sk-ant-...   # your Anthropic key — never committed
openosint --web &                      # start the web server on :8080
make demo                              # record -> encode -> write docs/assets/demo-web-graph.*
git add docs/assets/demo-web-graph.*
```

See [`scripts/record-demo/README.md`](scripts/record-demo/README.md) for full prerequisites and pipeline details.

## Maintainer

**Tommaso Bertocchi**  
- X (personal): https://x.com/SonoTommy_  
- X (OpenOSINT): https://x.com/openosint_oss  
- LinkedIn: https://www.linkedin.com/company/openosintoss  
- Email: openosint@yahoo.com

## Contributors

| Contributor | Contribution |
|---|---|
| [@consocio](https://github.com/consocio) | venv/uv-tool binary resolution fix — co-installed tools are now found without a separate activation step ([#6](https://github.com/OpenOSINT/OpenOSINT/pull/6)) |

## License

OpenOSINT is open source under the [MIT License](./LICENSE) — free for any use, including personal, commercial, academic, and closed-source.

---

¹ 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.25.0 — July 2026*

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=OpenOSINT/OpenOSINT&type=Date)](https://star-history.com/#OpenOSINT/OpenOSINT&Date)
