Building an Autonomous OSINT Agent: Claude API Meets Python

By ✦ min read

Why Manual OSINT Workflows Are Inefficient

Open Source Intelligence (OSINT) is a critical skill for security researchers, journalists, and threat analysts. The typical OSINT investigation follows a repetitive pattern: start with an email address, run a tool like holehe to find platform registrations, copy a username to sherlock across hundreds of sites, then manually check services like HaveIBeenPwned and WHOIS. Each tool is an isolated silo, and every pivot requires manual copying and pasting. The entire investigation logic—what to run next and how to interpret findings—lives only in your head. When you close the terminal, that reasoning disappears. This fragmented approach is not only time-consuming but also error-prone, as it relies on the analyst's memory and discipline.

Building an Autonomous OSINT Agent: Claude API Meets Python — Source: www.freecodecamp.org

The OpenOSINT Solution: A Python Framework with an AI Core

OpenOSINT is an open-source Python framework that replaces the manual workflow with an autonomous AI agent. Built on top of Claude’s Tool Use API, it chains OSINT tools together, executes them against real binaries, and saves a structured Markdown report. The key design principle: hallucination in tool results is structurally impossible because the agent always runs the actual tool and uses its real output. You can use OpenOSINT in three distinct ways:

1. Interactive AI REPL

Describe your target in natural language—for example, investigate target@example.com—and the agent decides which tools to run, in what order, and how to chain results. The output is a live terminal session where you see each step: generating dorks, searching email, collecting usernames, and more.

2. Direct CLI for Scripting

If you need to run individual tools without the AI layer, OpenOSINT provides a direct command-line interface. This is perfect for integrating into larger automation pipelines or when you want full control over each tool's parameters.

3. MCP Server for Claude Desktop

OpenOSINT can be exposed as an MCP (Model Context Protocol) server, making all its tools available directly within Claude Code or Claude Desktop. This allows you to trigger OSINT investigations from the AI chat interface without leaving the conversation.

How the Tool Use API Powers Autonomous Investigations

Claude’s Tool Use API is the engine behind OpenOSINT. Instead of just generating text, Claude can request the execution of specific functions—like search_email or whois_lookup—and the Python runtime fulfills those requests. The agent loop works like this:

You provide a target in natural language.
Claude decides which tool to call and with what arguments.
The tool runs locally (or via an API) and returns real-world data.
Claude interprets the results and decides the next action
The cycle repeats until the investigation is complete or you stop it.

Because the agent always reads the actual output of each binary or service, there is no risk of the AI inventing facts. This makes OpenOSINT trustworthy for security research where accuracy is paramount.

Installation and Setup

To get started, you need Python 3.10+, an Anthropic API key, and the OpenOSINT repository. The setup is straightforward:

Clone the repo from GitHub.
Install dependencies with pip install -r requirements.txt
Set your ANTHROPIC_API_KEY environment variable.
Run the interactive REPL with python -m openosint

The framework includes popular OSINT tools like holehe, sherlock, theHarvester, and WHOIS lookup binaries. You can also add custom tools by extending the tool registry.

Under the Hood: Agent Loop and Reliability

The agent loop is implemented as a while loop that continuously asks Claude for the next action until a stop signal or final answer. Each tool is defined as a Python function with a schema (name, description, parameters) that Claude can choose from. After the tool runs, its raw output is fed back into Claude's context, ensuring every decision is based on real data. This architecture eliminates AI hallucinations in results because the AI never generates synthetic tool responses—it only interprets what the tools actually returned.

Practical Example: Investigating an Email

Here’s what a real session looks like:

$ openosint
openosint ❯ investigate target@example.com

  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_username('targetuser')
  ✓ Found profiles on 12 platforms

  → whois_lookup('target.com')
  ✓ Registrar: GoDaddy, Org: ACME Inc.

  → Final Report saved to reports/2025-02-19_target.md

The agent automatically chains the tools, extracts usernames from email registrations, and runs additional lookups without manual intervention.

Project Architecture

OpenOSINT is structured into a few core modules:

agent/ – The AI loop that calls Claude’s API and orchestrates tool execution.
tools/ – Each OSINT function (holehe, sherlock, etc.) as a callable Python object with metadata.
cli/ – The command-line entry points: REPL mode and direct tool CLI.
mcp/ – The MCP server adapter for integration with Claude Desktop/Code.
reports/ – Auto-generated Markdown reports with timestamps and structured findings.

Because every tool returns plain text or JSON, adding a new tool requires only writing a thin wrapper function and registering it with the agent. The framework scales easily to dozens of OSINT utilities.

Conclusion

Automating OSINT investigations with an AI agent saves hours of repetitive manual work. OpenOSINT demonstrates how Claude’s Tool Use API can turn a collection of disjointed command-line tools into a coherent, autonomous investigation pipeline. Because the agent sees real tool output, you can trust the results. Whether you use the interactive REPL for ad‑hoc probes, the direct CLI for scripts, or the MCP server for chat‑based analysis, OpenOSINT puts the power of an entire OSINT toolkit at your fingertips—guided by AI, but grounded in reality.

Tags: