# OpenOSINT

> An AI agent that chains 20 OSINT lookups from one plain-language prompt

- Category: Agents & Automation / Security Agents
- Language: Python
- Licence: MIT
- Repository: https://github.com/OpenOSINT/OpenOSINT
- Website: https://openosint.tech
- Canonical page: https://ai-tldr.dev/tools/openosint/

## In short

OpenOSINT is an open-source intelligence (OSINT) agent for security researchers and analysts. It sits in the Security Agents category of the Agents & Automation tools and is open-source, written in Python and licensed MIT. To get started: install the package.

## Overview

OpenOSINT is an open-source intelligence (OSINT) agent for security researchers and analysts. You describe a target in plain language — an email address, a username, a domain, an IP — and an LLM decides which of its 20 investigation tools to run, then chains follow-up lookups on whatever it finds, for example pivoting from an email's linked accounts to a username search across other platforms. Every investigation ends in a saved Markdown report, with PDF export available.

The design point is that the model only issues tool calls; the project's own Python code executes the real lookup — holehe for email accounts, sherlock for usernames, HaveIBeenPwned for breaches, python-whois, sublist3r, phoneinfoga, dnspython, and the Shodan, VirusTotal, Censys, AbuseIPDB, IP2Location, GitHub and GDELT APIs. The agent cannot browse freely or run arbitrary code, so every finding traces back to a real tool call, though its choice of tools can still be wrong or incomplete.

It ships as a pip package with four interfaces over the same toolset: an interactive REPL, a browser web UI, direct CLI subcommands that skip the AI entirely, and an MCP server that exposes all 20 tools to Claude Code, Claude Desktop or any MCP client. The agent runs on Anthropic Claude by default, a local Ollama model, or any OpenAI-compatible endpoint. The project states it is for legal, authorised security research only.

## What it does

- AI tool chaining: the agent picks tools from the findings so far and pivots across email, username, domain and IP leads
- 20 lookup tools covering email accounts, usernames across 400+ platforms, breach exposure, WHOIS, subdomains, DNS with SPF/DMARC/DKIM analysis, phone numbers, pastes, Google dorks and threat-intel APIs
- Three model backends: Anthropic Claude, local Ollama, or any OpenAI-compatible endpoint such as LiteLLM, vLLM or LM Studio
- Native MCP server exposing all 20 tools to Claude Code, Claude Desktop and other MCP clients
- Optional FollowTheMoney entity graph with statement-level provenance and a human review queue for same_as deduplication candidates
- Markdown and PDF reports after each investigation, saved session history, parallel tool execution with --parallel and JSON output with --json

## Getting started

OpenOSINT installs from PyPI. Several key-less tools work with zero configuration; the AI agent needs an Anthropic key, a local Ollama model or an OpenAI-compatible endpoint, and some lookups need their provider's API key.

1. Install the package

   The email, username, subdomain and phone tools shell out to holehe, sherlock, sublist3r and phoneinfoga, which must be on your PATH; if one is missing only that tool returns an error.

```bash
pip install openosint

# optional external binaries
pip install holehe sherlock-project sublist3r
```

2. Add your keys to a .env file

   Copy .env.example to .env in the directory you run openosint from. ANTHROPIC_API_KEY powers the default agent; tool keys such as HIBP_API_KEY, SHODAN_API_KEY or VIRUSTOTAL_API_KEY are only needed for those tools.

```text
ANTHROPIC_API_KEY=...
HIBP_API_KEY=...
```

3. Run a single tool without the AI

   Each lookup is also a plain CLI subcommand, useful for scripting or a quick check.

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

4. Start the AI REPL and investigate a target

   With no arguments openosint opens the interactive agent. Type a target and it chains tools on the findings, then saves a report under reports/.

```bash
openosint
openosint > investigate target@example.com
```

5. Or use the web UI, fully local if you like

   The web extra opens a browser chat on localhost:8080. Pick Ollama (local) in Settings to run without an API key.

```bash
pip install "openosint[web]"
ollama pull llama3.2
openosint web
```

6. Expose the tools to Claude Code over MCP

```bash
claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py
claude mcp list
```

## When to use it

- Reach for it when you want to map a person's or organisation's public footprint from a single email or username during an authorised investigation
- Reach for it for attack-surface reconnaissance on a domain you own: subdomains, DNS and email-security records, exposed services via Shodan or Censys
- Reach for it when you want OSINT lookups available as tools inside Claude Code or another MCP client rather than in a separate app
- Reach for it for quick IP or file-hash triage against VirusTotal and AbuseIPDB from the command line
