Hermes OSINT v3.0 🏛️🧠

The Agentic OSINT Analyst
Conversational AI-driven investigations. Natural language. Expert results. 🤖✨

---

What's New in v3.0 🎉

Hermes 3.0 represents a complete paradigm shift from pipeline-based tool orchestration to a conversational AI-driven investigation platform. Powered by local LLMs via Ollama, Hermes now understands natural language queries, autonomously selects and executes tools, and synthesizes findings into coherent intelligence reports.

🧠 Agentic Intelligence

• Natural Language Interface - Ask questions like "Find everything about @johndoe" instead of memorizing CLI flags
• ReAct Pattern - Think → Act → Observe cycle for intelligent, iterative investigations
• Autonomous Tool Selection - LLM decides which tools to run based on context
• Citation-Based Reporting - Every finding is attributed to its source tool

💬 Interactive TUI

• Conversational REPL - Chat with Hermes in a pentester-themed terminal interface
• Session Persistence - Save and resume investigations with /save and /load
• Context Management - Automatic summarization prevents token overflow in long sessions
• Real-time Status Bar - Model, context usage, and stealth mode at a glance

🔄 Flexible Execution Modes

• TUI Mode (default) - Full conversational experience with Ollama
• Headless Mode - --headless --query "..." for scripting and automation
• Legacy Mode - hermes sherlock <user> for direct tool access without LLM

---

Overview 🎯

Hermes is a universal OSINT orchestration platform that unifies best-in-class open-source intelligence tools into a single, AI-powered workflow. Instead of manually running Sherlock, TheHarvester, Holehe, and other tools separately—wasting precious investigation time ⏰—Hermes's agentic core understands your intent, orchestrates tools intelligently, correlates results across sources, and delivers professional reports. 📊

What makes Hermes different: 🌟

• 🧠 Agentic AI with ReAct pattern—let the LLM drive your investigation
• 💬 Natural language queries—no flags to memorize, just describe what you need
• 🔒 Security-first plugin architecture with static code analysis—trust is earned
• 🐳 Docker isolation for zero-trust tool execution—sandbox everything
• ⚡ Parallel processing with intelligent resource management—2x faster than sequential
• 🧩 Cross-tool correlation engine for relationship mapping—connect the dots automatically
• 🔧 Extensible design—add new tools without touching core code

---

Features 💎

Agentic Core 🤖

• ReAct Agent Loop with Think → Act → Observe cycle
• Ollama Integration for local LLM inference (Llama 3, Mistral, etc.)
• Tool Registry with JSON Schema definitions for function calling
• Context Manager with rolling summaries (24k char limit for 8B models)
• Session Store for saving/loading investigation state

Interactive TUI 💻

• prompt_toolkit REPL with persistent history (~/.hermes_history)
• Pentester-themed styling with green/cyan/orange accents
• Dynamic status bar showing model, context %, and mode
• Slash commands: /help, /tools, /status, /save, /load, /export, /clear, /exit

Tool Orchestration 🎼

• 6 integrated OSINT tools out of the box (Sherlock, TheHarvester, h8mail, Holehe, PhoneInfoga, Subfinder) 🛠️
• Plugin architecture for seamless third-party tool integration 🔌
• Static security scanner validates plugin code before execution—no surprises! 🛡️
• Multi-mode execution: Docker containers, native binaries, or hybrid auto-detection 🎭
• Stealth mode enforcement - blocks active probing tools when enabled 🥷

Performance 🚀

• Parallel execution delivers 2x speed improvement over sequential runs ⚡
• Smart resource scaling auto-detects CPU cores and memory 💻
• Ephemeral containers spin up, execute, and destroy automatically 🌪️
• Configurable workers via --workers flag for fine-tuned concurrency 🎛️

Intelligence 🧠

• Cross-tool correlation identifies connections between disparate data sources 🔍
• Fuzzy deduplication eliminates redundant findings intelligently 🎯
• Unified entity schema normalizes output across all tools 📐
• Source attribution tracks which tool discovered each finding 📝
• Confidence scoring quantifies reliability of findings ⭐

---

Quick Start 🏃‍♂️💨

Prerequisites ✅

• Python 3.10 or higher 🐍
• Docker (for containerized tool execution) 🐳
• Ollama with a model installed (for TUI/agentic mode) 🧠

Installation 📦

# Clone and install
git clone https://github.com/Expert21/hermes-osint.git
cd hermes-osint
pip install -r requirements.txt
pip install .

# Install Ollama and pull a model
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1:8b

# Health check
hermes --doctor  # 🏥 Make sure everything's ready!

Basic Usage 🎮

# 🧠 TUI Mode (default) - Conversational AI interface
hermes
# Then chat naturally: "Find social accounts for johndoe"

# 📜 Headless Mode - For scripting and automation
hermes --headless --query "Investigate the domain example.com"

# 🔧 Legacy Mode - Direct tool access (no LLM required)
hermes sherlock johndoe
hermes theharvester example.com
hermes holehe [email protected]

TUI Commands 💬

/help          # Show all commands
/tools         # List available investigation tools
/status        # Show current session status
/save          # Save session to file
/load          # Load a previous session
/sessions      # List all saved sessions
/export FILE   # Export report (md, pdf, html, csv, stix)
/stealth       # Toggle stealth mode
/clear         # Clear conversation
/exit          # Exit Hermes

Advanced Usage 🎯

# Stealth mode - passive tools only
hermes --stealth
# Blocks: sherlock, holehe, phoneinfoga
# Allows: theharvester, subfinder, h8mail

# Specific model selection
hermes --model mistral:7b

# Headless with output
hermes --headless --query "Find subdomains for target.com" --output report.md

---

Available Tools 🛠️

Tool	Purpose	Input Type	Stealth	Status
Sherlock 🕵️	Username enumeration across 300+ sites	Username	❌	✅
TheHarvester 🌾	Email/subdomain discovery from OSINT sources	Domain	✅	✅
h8mail 📧	Breach data correlation and lookup	Email	✅	✅
Holehe 🔍	Email account detection across 120+ platforms	Email	❌	✅
PhoneInfoga 📱	Phone number OSINT and carrier lookup	Phone	❌	✅
Subfinder 🗺️	Passive subdomain enumeration	Domain	✅	✅

---

Architecture 🏗️

v3.0 Agentic Architecture

User Input → CLI (cli.py)
                ├── TUI Mode → AgentLoop → Ollama → ToolExecutor → Adapters
                ├── Headless → AgentLoop → Single Query → Report
                └── Legacy → ToolExecutor Direct (no LLM)

Component Flow

┌─────────────┐
│ User Query  │ 💬 "Find info about johndoe"
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│   AgentLoop     │ 🧠 ReAct: Think → Act → Observe