Hermes OSINT v3.0 🏛️🧠

L'Analista OSINT Agentivo
Investigazioni guidate da IA conversazionale. Linguaggio naturale. Risultati da esperti. 🤖✨

Novità della v3.0 🎉

Hermes 3.0 rappresenta un completo cambio di paradigma: dall'orchestrazione degli strumenti basata su pipeline a una piattaforma investigativa guidata da IA conversazionale. Alimentato da LLM locali tramite Ollama, Hermes ora comprende query in linguaggio naturale, seleziona ed esegue autonomamente gli strumenti e sintetizza i risultati in report di intelligence coerenti.

🧠 Intelligenza Agentiva

• Interfaccia a Linguaggio Naturale - Fai domande come "Trova tutto su @johndoe" invece di memorizzare i flag della CLI
• Pattern ReAct - Ciclo Pensa → Agisci → Osserva per investigazioni intelligenti e iterative
• Selezione Autonoma degli Strumenti - L'LLM decide quali strumenti eseguire in base al contesto
• Report con Citazioni - Ogni risultato è attribuito allo strumento che lo ha originato

💬 TUI Interattiva

• REPL Conversazionale - Chatta con Hermes in un'interfaccia terminale a tema pentester
• Persistenza delle Sessioni - Salva e riprendi le investigazioni con /save e /load
• Gestione del Contesto - Il riepilogo automatico previene l'overflow dei token nelle sessioni lunghe
• Barra di Stato in Tempo Reale - Modello, utilizzo del contesto e modalità stealth a colpo d'occhio

🔄 Modalità di Esecuzione Flessibili

• Modalità TUI (predefinita) - Esperienza completamente conversazionale con Ollama
• Modalità Headless - --headless --query "..." per script e automazione
• Modalità Legacy - hermes sherlock <user> per l'accesso diretto agli strumenti senza LLM

Panoramica 🎯

Hermes è una piattaforma universale di orchestrazione OSINT che unifica i migliori strumenti di open-source intelligence in un unico flusso di lavoro potenziato dall'IA. Invece di eseguire manualmente Sherlock, TheHarvester, Holehe e altri strumenti separatamente—facendo perdere tempo prezioso alle investigazioni ⏰—il core agentivo di Hermes comprende le tue intenzioni, orchestra gli strumenti in modo intelligente, correla i risultati tra le fonti e produce report professionali. 📊

Cosa rende Hermes diverso: 🌟

• 🧠 IA Agentiva con pattern ReAct—lascia che sia l'LLM a guidare la tua investigazione
• 💬 Query in linguaggio naturale—nessun flag da memorizzare, descrivi semplicemente ciò che ti serve
• 🔒 Architettura plugin security-first con analisi statica del codice—la fiducia va guadagnata
• 🐳 Isolamento Docker per l'esecuzione degli strumenti in ottica zero-trust—metti tutto in sandbox
• ⚡ Elaborazione parallela con gestione intelligente delle risorse—2 volte più veloce della sequenziale
• 🧩 Motore di correlazione tra strumenti per la mappatura delle relazioni—collega i punti automaticamente
• 🔧 Design estensibile—aggiungi nuovi strumenti senza toccare il codice core

Funzionalità 💎

Core Agentivo 🤖

• Ciclo Agente ReAct con il ciclo Pensa → Agisci → Osserva
• Integrazione Ollama per l'inferenza LLM locale (Llama 3, Mistral, ecc.)
• Registro degli Strumenti con definizioni JSON Schema per il function calling
• Gestore del Contesto con riepiloghi progressivi (limite di 24k caratteri per i modelli 8B)
• Archivio Sessioni per salvare/caricare lo stato dell'investigazione

TUI Interattiva 💻

• REPL prompt_toolkit con cronologia persistente (~/.hermes_history)
• Stile a tema pentester con accenti verdi/ciano/arancio
• Barra di stato dinamica che mostra modello, % di contesto e modalità
• Comandi slash: /help, /tools, /status, /save, /load, /export, /clear, /exit

Orchestrazione degli Strumenti 🎼

• 6 strumenti OSINT integrati pronti all'uso (Sherlock, TheHarvester, h8mail, Holehe, PhoneInfoga, Subfinder) 🛠️
• Architettura a plugin per un'integrazione fluida degli strumenti di terze parti 🔌
• Scanner di sicurezza statico valida il codice dei plugin prima dell'esecuzione—nessuna sorpresa! 🛡️
• Esecuzione multi-modalità: container Docker, binari nativi o rilevamento automatico ibrido 🎭
• Applicazione della modalità stealth - blocca gli strumenti di probing attivo quando è abilitata 🥷

Prestazioni 🚀

• Esecuzione parallela offre un miglioramento di velocità di 2x rispetto alle esecuzioni sequenziali ⚡
• Scalabilità intelligente delle risorse rileva automaticamente core CPU e memoria 💻
• Container effimeri si avviano, eseguono e vengono distrutti automaticamente 🌪️
• Worker configurabili tramite il flag --workers per una concorrenza finemente calibrata 🎛️

Intelligenza 🧠

• Correlazione tra strumenti identifica le connessioni tra fonti di dati disparate 🔍
• Deduplicazione fuzzy elimina i risultati ridondanti in modo intelligente 🎯
• Schema unificato delle entità normalizza l'output di tutti gli strumenti 📐
• Attribuzione della fonte tiene traccia di quale strumento ha scoperto ogni risultato 📝
• Punteggio di confidenza quantifica l'affidabilità dei risultati ⭐

Avvio Rapido 🏃‍♂️💨

Prerequisiti ✅

• Python 3.10 o superiore 🐍
• Docker (per l'esecuzione containerizzata degli strumenti) 🐳
• Ollama con un modello installato (per la modalità TUI/agentiva) 🧠

Installazione 📦

# Clona e installa
git clone https://github.com/Expert21/hermes-osint.git
cd hermes-osint
pip install -r requirements.txt
pip install .

# Installa Ollama e scarica un modello
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1:8b

# Controllo di integrità
hermes --doctor  # 🏥 Assicurati che sia tutto pronto!

Utilizzo di Base 🎮

# 🧠 Modalità TUI (predefinita) - Interfaccia AI conversazionale
hermes
# Poi chatta in modo naturale: "Trova gli account social di johndoe"

# 📜 Modalità Headless - Per script e automazione
hermes --headless --query "Investigate the domain example.com"

# 🔧 Modalità Legacy - Accesso diretto agli strumenti (senza LLM)
hermes sherlock johndoe
hermes theharvester example.com
hermes holehe [email protected]

Comandi TUI 💬

/help          # Mostra tutti i comandi
/tools         # Elenca gli strumenti di investigazione disponibili
/status        # Mostra lo stato della sessione corrente
/save          # Salva la sessione su file
/load          # Carica una sessione precedente
/sessions      # Elenca tutte le sessioni salvate
/export FILE   # Esporta il report (md, pdf, html, csv, stix)
/stealth       # Attiva/disattiva la modalità stealth
/clear         # Pulisci la conversazione
/exit          # Esci da Hermes

Utilizzo Avanzato 🎯

# Modalità stealth - solo strumenti passivi
hermes --stealth
# Blocca: sherlock, holehe, phoneinfoga
# Consente: theharvester, subfinder, h8mail

# Selezione di un modello specifico
hermes --model mistral:7b

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

Strumenti Disponibili 🛠️

Architettura 🏗️

Architettura Agentiva v3.0

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

Flusso dei Componenti

┌─────────────┐
│ User Query  │ 💬 "Find info about johndoe"
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│   AgentLoop     │ 🧠 ReAct: Think → Act → Observe
│  (agent_loop.py)│
└────────┬────────┘
         │
         ├──────────────────┬────────────────┐
         ▼                  ▼                ▼
┌──────────────┐   ┌───────────────┐  ┌─────────────┐
│ ToolRegistry │   │ContextManager │  │ SessionStore│
│(tool_registry)│  │(context_mgr.py)│ │(session_store)│
└──────┬───────┘   └───────────────┘  └─────────────┘
       │
       ▼
┌──────────────────────┐
│   ToolExecutor       │ 🔧 Validates + Executes
│  (tool_executor.py)  │
└──────────┬───────────┘
           │
           ▼
┌─────────────────────────┐
│ ExecutionStrategy       │ 🎭 Docker/Native/Hybrid
│ (execution_strategy.py) │
└──────────┬──────────────┘
           │
           ▼
    ┌──────────────┐
    │ Tool Adapters│ 🔌 Sherlock, TheHarvester, etc.
    └──────┬───────┘
           │
           ▼
    ┌─────────────┐      ┌──────────────┐
    │ Raw Results │─────▶│Deduplication │ ✨
    └─────────────┘      └──────┬───────┘
                                │
                                ▼
                         ┌─────────────┐
                         │   Report    │ 📊
                         │ (exporter)  │
                         └─────────────┘

Componenti Chiave 🔑

Livello Agente (src/agent/)

• AgentLoop 🧠: pattern ReAct con function calling di Ollama
• ToolRegistry 📋: definizioni JSON Schema per l'uso degli strumenti da parte dell'LLM
• ToolExecutor 🔧: valida gli input, applica la modalità stealth, funge da ponte verso gli adapter
• ContextManager 📊: riepiloghi progressivi, previene l'overflow dei token
• SessionStore 💾: persistenza JSON per la funzionalità di salvataggio/caricamento
• TUI 💻: REPL prompt_toolkit con stile pentester

Livello di Orchestrazione (src/orchestration/)

• ExecutionStrategy 🎭: selezione della modalità Docker/Nativa/Ibrida
• DockerManager 🐳: container effimeri con verifica SHA256
• TaskManager ⚡: esecuzione parallela con limiti delle risorse

Livello di Sicurezza (src/security/)

• PluginSecurityScanner 🛡️: analisi statica basata su AST
• InputValidator ✅: prevenzione delle injection, protezione dal path traversal
• SecretsManager 🔐: archiviazione crittografata delle credenziali

Sicurezza 🔐

Sicurezza dell'Agente 🛡️

• Regole di grounding impediscono le speculazioni dell'LLM—cita le fonti o resta in silenzio
• Applicazione della modalità stealth blocca gli strumenti di probing attivo quando è abilitata
• Validazione degli input su tutti i parametri degli strumenti prima dell'esecuzione
• Limiti del contesto prevengono la prompt injection tramite overflow dei token

Isolamento dei Container 🐳🔒

• Ancoraggio del digest SHA256 previene la manomissione delle immagini ✅
• Ciclo di vita effimero distrugge i container immediatamente dopo l'esecuzione 🌪️
• Limiti delle risorse (768MB di RAM, 50% di CPU, 64 PID) 🚦
• Isolamento della rete con DNS configurabile e supporto proxy 🌐
• Esecuzione non-root (UID/GID 65534:65534) 👥

Sicurezza dei Plugin 🛡️

• Analisi statica rileva eval(), exec(), os.system() e l'iniezione di shell 🚨
• Modello di fiducia a due livelli separa i plugin Tool dai plugin Core 🏛️
• Dichiarazioni delle capability definiscono esplicitamente i permessi richiesti 📋

Formati di Output 📄

Hermes genera report in più formati tramite /export—i tuoi dati, a modo tuo! 🎨

📦 JSON - Dati strutturati per il consumo programmatico

📝 Markdown - Formato pulito e compatibile con GitHub, con tabelle

🌐 HTML - Design responsive con CSS incorporato e statistiche

📄 PDF - Formattazione professionale con sommario esecutivo

📊 CSV - Semplice formato tabellare per l'importazione in fogli di calcolo

🔒 STIX 2.1 - Formato standard di settore per la threat intelligence

Licenza ⚖️

AGPL-3.0 (Community Edition) 🆓

Hermes OSINT è concesso in licenza secondo la GNU Affero General Public License v3.0.

Cosa significa: 💡

• ✅ Gratuito per uso personale e commerciale
• ✅ Open source—visualizza, modifica e distribuisci il codice
• ✅ Copyleft—anche le modifiche devono essere rilasciate come open source secondo AGPL-3.0
• ⚠️ Uso in rete = Distribuzione—se esegui Hermes come servizio, devi condividere il tuo codice sorgente

Consulta il file LICENSE per i termini completi.

Casi d'Uso 💼

🔍 Ricerca sulla Sicurezza - Investiga le minacce con query in linguaggio naturale

🤝 Due Diligence - "Dimmi tutto su questa persona/azienda"

👣 Analisi dell'Impronta Digitale - Comprendi l'esposizione della tua organizzazione

📈 Competitive Intelligence - Ricerca i concorrenti in modalità conversazionale

🎯 Threat Intelligence - Raccogli indicatori con triage guidato dall'IA

📰 Giornalismo Investigativo - Lascia che Hermes colleghi i punti

Disclaimer Legale ed Etico ⚖️

Solo per attività OSINT autorizzate. ⚠️ Gli utenti sono gli unici responsabili dell'ottenimento delle dovute autorizzazioni, del rispetto delle leggi applicabili e dell'uso etico di questo strumento.

Usi consentiti: ✅

• Raccolta di informazioni disponibili pubblicamente
• Valutazioni di sicurezza autorizzate
• Analisi personale dell'impronta digitale
• Conformità alle leggi e ai regolamenti locali

Usi vietati: 🚫

• Molestie, stalking o intimidazioni
• Tentativi di accesso non autorizzato
• Violazioni delle leggi sulla privacy
• Violazioni dei Termini di Servizio delle piattaforme

Gli sviluppatori non si assumono alcuna responsabilità per l'uso improprio di questo strumento. 🙅‍♂️

Contributi 🤝

I contributi sono benvenuti! 🎉 Consulta PLUGIN_DEVELOPMENT.md per le linee guida sulla creazione di plugin e USAGE.md per la documentazione dettagliata sull'utilizzo.

Hai idee? Trovato bug? Vuoi aggiungere uno strumento? Apri una issue o invia una PR! 💪

Autore ✍️

Isaiah Myles (@Expert21)

Professionista emergente della cybersecurity | Mentalità da pentester | Costruttore di strumenti che contano 🛠️⚡

• 🐛 Issues: GitHub Issues
• 📧 Email: [email protected]