OpenOSINT — AI-powered OSINT Agent

Features

Why OpenOSINT?

The AI decides which tools to run and in what order. You provide the target — the agent plans, executes, and reports.

Native Tool Use

Uses Anthropic's stop_reason: tool_use — not a brittle ReAct loop. The model natively chains tools based on findings.

10 OSINT Modules

Email validation, username search across 17 platforms, WHOIS/DNS, IP geolocation, phone analysis, breach lookup, EXIF metadata, and dork generation.

Beautiful CLI

Rich-powered terminal interface with live tool output, spinners, colored panels, and structured Markdown reports saved automatically.

Interactive REPL

Conversational investigation session — ask follow-up questions, pivot on findings, and save reports mid-session. Or use one-shot mode for scripts.

Zero Friction

One API key to start. 8 of 10 tools work with no paid third-party APIs. Optional HaveIBeenPwned and AbuseIPDB keys add depth.

Open Source

MIT licensed. Clean architecture designed for extension — add new OSINT tools in under 50 lines. Multi-provider support built in.

Installation

Get up and running

OpenOSINT runs on Python 3.10+ and installs in under a minute.

01

Option A — pip install

bash

pip install openosint

—

or

01

Option B — clone & install

bash

git clone https://github.com/openosint/openosint
cd openosint
bash setup.sh          # creates .venv, installs deps
source .venv/bin/activate

02

Set your API key

bash

export ANTHROPIC_API_KEY=sk-ant-...
# or add it to a .env file (copy from .env.example)

Get a key at console.anthropic.com. Claude Sonnet offers the best results at the lowest cost.

03

Run your first investigation

bash

openosint                              # interactive REPL
openosint investigate john@example.com # one-shot
openosint investigate example.com --save

Configuration

Settings are read from environment variables, a .env file in the working directory, or ~/.config/openosint/config.json. Environment variables always win.

Environment variables

Variable	Default	Description
`ANTHROPIC_API_KEY`	—	Required for Anthropic provider
`OPENAI_API_KEY`	—	Required for OpenAI provider
`OPENOSINT_PROVIDER`	`anthropic`	`anthropic` · `openai` · `ollama`
`OPENOSINT_MODEL`	`claude-sonnet-4-20250514`	Override the default model
`HIBP_API_KEY`	—	HaveIBeenPwned API key (optional)
`ABUSEIPDB_API_KEY`	—	AbuseIPDB API key (optional)
`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama server URL

Config file

Use openosint config to update settings. API keys are never written to the config file — always use environment variables for secrets.

bash

openosint config --show                    # view current config
openosint config --provider openai         # switch provider
openosint config --model gpt-4o           # override model

💡

Tip: Create a .env file in your project directory for per-project API keys. OpenOSINT uses python-dotenv to load it automatically.

Providers

AI Providers

Swap AI providers with a single environment variable. Anthropic gives the best OSINT results; Ollama is free and runs locally.

Default Best Quality

Anthropic

Uses Claude's native stop_reason: tool_use API — no prompt engineering needed. The model genuinely understands investigation strategy and chains tools intelligently.

bash

export ANTHROPIC_API_KEY=sk-ant-...
# Default model: claude-sonnet-4-20250514
# Best balance of speed and quality

OpenAI

Compatible with GPT-4o and later models via the OpenAI function calling API. Good alternative when you already have an OpenAI subscription.

bash

export OPENAI_API_KEY=sk-...
export OPENOSINT_PROVIDER=openai
# Default model: gpt-4o

Ollama Local · Free

Run any Ollama model that supports function calling (llama3.1, qwen2.5, mistral-nemo). No API costs, full privacy — perfect for sensitive investigations.

bash

ollama pull llama3.1
export OPENOSINT_PROVIDER=ollama
export OPENOSINT_MODEL=llama3.1

Provider comparison

Feature	Anthropic ⭐	OpenAI	Ollama
Tool use quality	★★★★★	★★★★	★★★
Investigation depth	Best	Very good	Model-dependent
Native tool use API	✓ stop_reason	✓ function_call	~ Varies
API cost	Paid	Paid	Free
Privacy	Good	Good	Best (local)
Speed	Fast	Fast	Hardware-limited
Recommended model	`claude-sonnet-4-20250514`	`gpt-4o`	`llama3.1`

Tools Reference

OSINT Tools

All 10 tools are invoked autonomously by the AI agent. They can also be used directly via the Python API.

Tool	Target	Data Sources	API Key
`check_email`	Email	DNS/MX · provider detection · disposable DB	Free
`check_username`	Username	GitHub · Reddit · Twitter/X · Instagram · TikTok · YouTube · Twitch · +10	Free
`check_domain`	Domain	WHOIS · DNS (A/MX/NS/TXT) · SSL cert · HTTP headers	Free
`check_ip`	IP address	ip-api.com · reverse DNS · AbuseIPDB (opt.)	Optional
`check_phone`	Phone	libphonenumber · country · carrier · line type	Free
`check_breach`	Email	HaveIBeenPwned v3 · breaches + pastes	HIBP key
`check_metadata`	Image URL	EXIF · GPS coordinates · camera model · timestamps	Free
`generate_dorks`	Any	Google/Bing dork generation (no external API)	Free
`dns_lookup`	Domain	A · AAAA · MX · NS · TXT · CNAME · SOA · PTR	Free
`whois_lookup`	Domain / IP	WHOIS · registrar · dates · nameservers	Free

ℹ

Get HaveIBeenPwned access at haveibeenpwned.com/API/Key ($3.50/month). AbuseIPDB has a free tier at abuseipdb.com/api.

CLI Reference

Interactive mode

Launch with no arguments. The agent maintains conversation context — ask follow-up questions after an investigation.

terminal

openosint

openosint ❯ john.doe@gmail.com
openosint ❯ What about related domains?
openosint ❯ save
openosint ❯ quit

Interactive commands

Command	Description
`<target>`	Start an investigation on any target
`investigate <target>`	Explicit investigation
`clear`	Reset conversation history
`save`	Save last report to `reports/`
`help`	Show available commands
`quit` / `exit`	Exit

One-shot investigation

bash

openosint investigate <target> [OPTIONS]

Options:
  -s, --save         Save report to reports/ directory
  -o, --output PATH  Save to specific file path
  -q, --quiet        Suppress banner (clean pipe output)
  -h, --help         Show help

bash

# Examples
openosint investigate john@example.com
openosint investigate example.com --save
openosint investigate 8.8.8.8 --output /tmp/report.md
openosint investigate "@johndoe" --quiet | grep "Account Discovery" -A 20

Configuration command

bash

openosint config [OPTIONS]

Options:
  --show             Show current configuration
  --provider TEXT    Set AI provider (anthropic|openai|ollama)
  --model TEXT       Override default model

Python API

Use OpenOSINT as a Python library. All components are importable and testable independently.

Agent API

python

from openosint.config import Config
from openosint.display import Display
from openosint.agent import OpenOSINTAgent

config = Config.load()             # reads .env + env vars
display = Display(quiet=True)      # suppress banner for library use
agent = OpenOSINTAgent(config, display)

# One-shot investigation
report = agent.investigate("example.com")
print(report)

# Multi-turn investigation
agent.investigate("john@example.com")
follow_up = agent.chat("What about related domains?")

# Save report to file
path = agent.save_report(report, "example.com")
print(f"Saved to {path}")

Direct tool usage

python

from openosint.tools.email_tools import check_email
from openosint.tools.domain_tools import check_domain
from openosint.tools.username_tools import check_username
from openosint.tools.ip_tools import check_ip

# Email intelligence
result = check_email("user@example.com")
print(result["valid"])           # True/False
print(result["provider"])        # "Google" / "Microsoft" / ...
print(result["mx_records"])      # list of MX records
print(result["username_variants"])  # ["user", "userexample", ...]

# Domain intelligence
domain = check_domain("example.com")
print(domain["ssl"]["issuer"])   # SSL certificate issuer
print(domain["dns"]["TXT"])      # TXT records (SPF, DMARC, etc.)
print(domain["http_headers"])    # interesting response headers

# Username across platforms (returns found URLs)
usernames = check_username("johndoe")
for found in usernames["found"]:
    print(f"{found['platform']}: {found['url']}")

Contributing

Contributions are welcome. The most impactful contributions are new OSINT tools and platform support for the username checker.

Adding a new OSINT tool

Each tool is a Python function that accepts named parameters and returns a dict[str, Any] with a status key.

1

Create the tool module

python

# openosint/tools/my_tool.py
from typing import Any

def my_tool(target: str) -> dict[str, Any]:
    """Investigate something about target."""
    return {
        "status": "ok",
        "target": target,
        # ... your findings
    }

2

Register in registry.py

Add to TOOL_DEFINITIONS and the execute_tool() dispatcher in openosint/tools/registry.py.

python

# In TOOL_DEFINITIONS list:
{
    "name": "my_tool",
    "description": "Clear description of what this investigates.",
    "input_schema": {
        "type": "object",
        "properties": {
            "target": {"type": "string", "description": "..."}
        },
        "required": ["target"],
    },
},

# In execute_tool():
elif name == "my_tool":
    from .my_tool import my_tool
    return my_tool(inputs["target"])

3

Add icon and tests

Add an icon to TOOL_ICONS in display.py and write unit tests in tests/test_tools.py.

💡

Guidelines: Tools should return {"status": "error", "error": "..."} on failure, never raise exceptions. Include a "notes" list for advisory messages. Always handle network timeouts gracefully.

Legal & Ethics

⚠️

This tool is for authorized use only.

OpenOSINT is designed for legal, ethical, and authorized security research, OSINT investigations, and educational purposes only. The authors accept no liability for misuse.

By using OpenOSINT you agree to investigate only targets for which you have explicit authorization or a legitimate legal basis, and to comply with all applicable laws including GDPR, CCPA, and the Computer Fraud and Abuse Act (CFAA). Any consequences from use of this tool are your sole responsibility.

Legitimate Uses ✓

✓ Authorized security research & penetration testing
✓ Investigative journalism on matters of public interest
✓ Law enforcement with proper warrant or authorization
✓ Investigating your own accounts & digital footprint
✓ CTF challenges and security education
✓ Digital forensics and incident response

Prohibited Uses ✗

✗ Stalking, harassment, or doxxing any individual
✗ Unauthorized surveillance of persons or organizations
✗ Identity theft, fraud, or social engineering attacks
✗ Collecting personal data without legal basis (GDPR/CCPA)
✗ Any activity violating another person's privacy or dignity
✗ Investigations without explicit target authorization

For the full disclaimer, warranty notice, and third-party tool terms, see DISCLAIMER.md on GitHub.

Changelog

v1.0.0 May 2026

Initial release
Native Anthropic tool use loop (stop_reason: tool_use)
10 OSINT modules: email, username (17 platforms), domain, IP, phone, breach, EXIF metadata, dork generation, DNS, WHOIS
Multi-provider: Anthropic (default), OpenAI, Ollama
Interactive REPL + one-shot investigate command
Auto-saved Markdown reports
Rich terminal UI with live tool output
Documentation site

Upcoming

Async parallel tool execution
Report templates (executive, technical, journalist)
Plugin system for custom tools
OSINT result caching layer
Shodan and Censys integration