Darhost

Introduction

When I started studying OSINT, I often felt like I was blindly feeding commands into tools without truly understanding the investigation. After months in the field, I realized that most OSINT workflows follow predictable patterns—copy, paste, run, repeat. That repetitiveness is exactly where an AI agent shines. So I built one.

This guide will walk you through creating OpenOSINT, an open-source Python framework that pairs OSINT tools with Claude's native tool-use capability. By the end, you'll be able to run autonomous investigations using three modes: an interactive REPL, a direct CLI for scripting, and an MCP server that exposes all tools to Claude Desktop or Claude Code. You'll also learn the core design principle that prevents hallucination in tool results—a must for security research.

Let's get started.

What You Need

Before diving in, make sure you have the following:

• Python 3.10 or later installed on your system
• A Claude API key (from Anthropic) with access to the Tool Use API
• pip and git for installation
• Basic familiarity with the terminal and Python
• (Optional) Claude Desktop or Claude Code if you plan to use the MCP server

Step-by-Step Instructions

Step 1: Clone the OpenOSINT Repository

Open your terminal and run the following command to clone the project:

git clone https://github.com/your-username/openosint.git

Navigate into the directory:

cd openosint

Step 2: Set Up a Virtual Environment and Install Dependencies

It's a good practice to isolate your project dependencies. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the required packages:

pip install -r requirements.txt

Step 3: Configure Your Claude API Key

OpenOSINT uses Claude's Tool Use API, so you need to provide your API key. Create a .env file in the project root and add:

ANTHROPIC_API_KEY=your_api_key_here

Alternatively, you can export the environment variable in your shell profile. The framework will read it automatically.

Step 4: Understand How Claude's Tool Use Works

Claude's Tool Use API lets the model decide which external tools to call based on your natural language request. In OpenOSINT, each OSINT tool (like holehe or sherlock) is wrapped as a function that Claude can invoke. When you ask to investigate an email, Claude picks the appropriate tool, runs it, gets the result, and decides the next action—all autonomously. The key is that the tool results come from real binaries, not AI generation, so hallucination is impossible in those data.

Step 5: Run the Interactive AI REPL

The most user-friendly way to use OpenOSINT is through the interactive REPL. Launch it with:

python openosint.py

You'll see a prompt like openosint ❯. Type a natural language command, for example:

investigate target@example.com

The agent will internally call tools such as generate_dorks, search_email, and search_username, and display the findings in real time. You can ask follow-up questions, and the agent will chain additional tools as needed.

Step 6: Use the Direct CLI for Scripting

If you want to run individual tools without the AI loop, the direct CLI mode is perfect. For example:

python openosint.py --tool holehe --email target@example.com

This runs the tool and prints the output immediately. You can chain multiple commands in a shell script, making it easy to integrate into larger workflows.

Step 7: Set Up the MCP Server

MCP (Model Context Protocol) allows you to expose all OpenOSINT tools to Claude Desktop or Claude Code. Start the MCP server with:

python openosint.py --mcp

Then, in your Claude Desktop or Claude Code, configure it to connect to http://localhost:8000 (or the port specified). Now you can ask Claude to perform OSINT investigations directly from your preferred interface, using the same underlying tools.

Step 8: Understand the Agent Loop (Under the Hood)

The heart of OpenOSINT is the agent loop:

1. The user submits a query.
2. Claude analyzes the query and chooses a tool to run.
3. The tool executes against real data (e.g., querying public APIs or running local binaries).
4. The output is fed back to Claude as context.
5. Claude decides the next step: run another tool, ask a clarifying question, or produce a final report.
6. When the investigation concludes, a structured Markdown report is saved locally.

This loop ensures that every piece of evidence comes from a real OSINT tool, not from the AI's internal knowledge. This is what makes it trustworthy.

Tips and Best Practices

• Start with a small test target – use a known email or username to verify the tool chain works.
• Monitor your API usage – each tool call consumes tokens, so keep an eye on your Claude API dashboard.
• Customize tool selection – the framework is open source; you can add or remove tools by editing the tool registry.
• Save reports automatically – the agent saves a Markdown report after each investigation. Review it to refine your workflow.
• Combine with other data sources – extend OpenOSINT with your own custom tools (e.g., scanning for exposed credentials).
• Use the MCP server for complex investigations – if you already work with Claude Desktop, expose the tools there for a seamless experience.

Remember: the strength of this approach is that the AI orchestrates, but doesn't fabricate, the data. Each output is grounded in real public sources. Happy investigating!