expert21/hermes-osintHermes — um framework OSINT efêmero, impulsionado por Docker, para testes, experimentação e automação investigativa segura.
# Hermes OSINT v3.0 🏛️🧠 > **O Analista OSINT Agêntico** > Investigações orientadas por IA conversacional. Linguagem natural. Resultados especializados. 🤖✨ [](https://github.com/Expert21/hermes-osint/releases) [](https://www.gnu.org/licenses/agpl-3.0) [](https://www.python.org/downloads/) [](https://www.docker.com/) [](https://ollama.ai/) --- ## Novidades na v3.0 🎉 **Hermes 3.0** representa uma mudança completa de paradigma, passando da orquestração de ferramentas baseada em pipelines para uma **plataforma de investigação orientada por IA conversacional**. Com LLMs locais via Ollama, o Hermes agora entende consultas em linguagem natural, seleciona e executa ferramentas autonomamente e sintetiza descobertas em relatórios de inteligência coerentes. ### 🧠 Inteligência Agêntica - **Interface de Linguagem Natural** - Faça perguntas como "Encontre tudo sobre @johndoe" em vez de memorizar flags de CLI - **Padrão ReAct** - Ciclo Pensar → Agir → Observar para investigações iterativas e inteligentes - **Seleção Autônoma de Ferramentas** - O LLM decide quais ferramentas executar com base no contexto - **Relatórios com Citações** - Cada descoberta é atribuída à sua ferramenta de origem ### 💬 TUI Interativa - **REPL Conversacional** - Converse com o Hermes em uma interface de terminal temática de pentest - **Persistência de Sessão** - Salve e retome investigações com `/save` e `/load` - **Gerenciamento de Contexto** - Sumarização automática evita estouro de tokens em sessões longas - **Barra de Status em Tempo Real** - Modelo, uso de contexto e modo stealth à vista ### 🔄 Modos de Execução Flexíveis - **Modo TUI** (padrão) - Experiência conversacional completa com Ollama - **Modo Headless** - `--headless --query "..."` para scripting e automação - **Modo Legado** - `hermes sherlock <user>` para acesso direto a ferramentas sem LLM --- ## Visão Geral 🎯 O Hermes é uma **plataforma universal de orquestração OSINT** que unifica as melhores ferramentas de inteligência de código aberto em um único fluxo de trabalho com IA. Em vez de executar manualmente Sherlock, TheHarvester, Holehe e outras ferramentas separadamente—**perdendo precioso tempo de investigação** ⏰—o núcleo agêntico do Hermes entende sua intenção, orquestra ferramentas de forma inteligente, correlaciona resultados entre fontes e entrega relatórios profissionais. 📊 **O que torna o Hermes diferente:** 🌟 - 🧠 **IA Agêntica** com padrão ReAct—deixe o LLM conduzir sua investigação - 💬 **Consultas em linguagem natural**—sem flags para memorizar, apenas descreva o que precisa - 🔒 **Arquitetura de plugins com segurança em primeiro lugar** e análise estática de código—a confiança é conquistada - 🐳 **Isolamento Docker** para execução de ferramentas com confiança zero—sandbox para tudo - ⚡ **Processamento paralelo** com gerenciamento inteligente de recursos—2x mais rápido que sequencial - 🧩 **Mecanismo de correlação entre ferramentas** para mapeamento de relacionamentos—conecte os pontos automaticamente - 🔧 **Design extensível**—adicione novas ferramentas sem tocar no código principal --- ## Funcionalidades 💎 ### Núcleo Agêntico 🤖 - **Loop de Agente ReAct** com ciclo Pensar → Agir → Observar - **Integração com Ollama** para inferência local de LLM (Llama 3, Mistral, etc.) - **Registro de Ferramentas** com definições em JSON Schema para chamada de funções - **Gerenciador de Contexto** com sumários rolantes (limite de 24k caracteres para modelos 8B) - **Armazenamento de Sessão** para salvar/carregar estado da investigação ### TUI Interativa 💻 - **REPL com prompt_toolkit** e histórico persistente (`~/.hermes_history`) - **Estilo temático de pentest** com acentos verde/ciano/laranja - **Barra de status dinâmica** mostrando modelo, % de contexto e modo - **Comandos com barra**: `/help`, `/tools`, `/status`, `/save`, `/load`, `/export`, `/clear`, `/exit` ### Orquestração de Ferramentas 🎼 - **6 ferramentas OSINT integradas** prontas para uso (Sherlock, TheHarvester, h8mail, Holehe, PhoneInfoga, Subfinder) 🛠️ - **Arquitetura de plugins** para integração perfeita de ferramentas de terceiros 🔌 - **Scanner de segurança estático** valida o código do plugin antes da execução—sem surpresas! 🛡️ - **Execução em múltiplos modos**: contêineres Docker, binários nativos ou detecção automática híbrida 🎭 - **Imposição de modo stealth** - bloqueia ferramentas de sondagem ativa quando ativado 🥷 ### Desempenho 🚀 - **Execução paralela** oferece **melhoria de 2x na velocidade** em relação a execuções sequenciais ⚡ - **Escalonamento inteligente de recursos** detecta automaticamente núcleos de CPU e memória 💻 - **Contêineres efêmeros** giram, executam e são destruídos automaticamente 🌪️ - **Workers configuráveis** via flag `--workers` para concorrência ajustada 🎛️ ### Inteligência 🧠 - **Correlação entre ferramentas** identifica conexões entre fontes de dados díspares 🔍 - **Desduplicação fuzzy** elimina descobertas redundantes de forma inteligente 🎯 - **Esquema de entidade unificado** normaliza a saída de todas as ferramentas 📐 - **Atribuição de fonte** rastreia qual ferramenta descobriu cada resultado 📝 - **Pontuação de confiança** quantifica a confiabilidade das descobertas ⭐ --- ## Início Rápido 🏃♂️💨 ### Pré-requisitos ✅ - Python 3.10 ou superior 🐍 - Docker (para execução de ferramentas em contêiner) 🐳 - Ollama com um modelo instalado (para modo TUI/agêntico) 🧠 ### Instalação 📦 ```bash # Clone e instale git clone https://github.com/Expert21/hermes-osint.git cd hermes-osint pip install -r requirements.txt pip install . # Instale o Ollama e baixe um modelo curl -fsSL https://ollama.com/install.sh | sh ollama pull llama3.1:8b # Verificação de saúde hermes --doctor # 🏥 Verifique se está tudo pronto! ``` ### Uso Básico 🎮 ```bash # 🧠 Modo TUI (padrão) - Interface conversacional com IA hermes # Depois converse naturalmente: "Encontre contas sociais para johndoe" # 📜 Modo Headless - Para scripting e automação hermes --headless --query "Investigue o domínio exemplo.com" # 🔧 Modo Legado - Acesso direto a ferramentas (sem LLM) hermes sherlock johndoe hermes theharvester example.com hermes holehe [email protected] ``` ### Comandos TUI 💬 ```bash /help # Mostra todos os comandos /tools # Lista ferramentas de investigação disponíveis /status # Mostra status da sessão atual /save # Salva sessão em arquivo /load # Carrega uma sessão anterior /sessions # Lista todas as sessões salvas /export FILE # Exporta relatório (md, pdf, html, csv, stix) /stealth # Alterna modo stealth /clear # Limpa conversa /exit # Sai do Hermes ``` ### Uso Avançado 🎯 ```bash # Modo stealth - apenas ferramentas passivas hermes --stealth # Bloqueia: sherlock, holehe, phoneinfoga # Permite: theharvester, subfinder, h8mail # Seleção específica de modelo hermes --model mistral:7b # Headless com saída hermes --headless --query "Encontre subdomínios para target.com" --output report.md ``` --- ## Ferramentas Disponíveis 🛠️ | Ferramenta | Finalidade | Tipo de Entrada | Stealth | Status | |------------|------------|-----------------|---------|--------| | **Sherlock** 🕵️ | Enumeração de nomes de usuário em mais de 300 sites | Nome de usuário | ❌ | ✅ | | **TheHarvester** 🌾 | Descoberta de e-mails/subdomínios de fontes OSINT | Domínio | ✅ | ✅ | | **h8mail** 📧 | Correlação e consulta de dados de violações | E-mail | ✅ | ✅ | | **Holehe** 🔍 | Detecção de contas de e-mail em mais de 120 plataformas | E-mail | ❌ | ✅ | | **PhoneInfoga** 📱 | OSINT de números de telefone e consulta de operadora | Telefone | ❌ | ✅ | | **Subfinder** 🗺️ | Enumeração passiva de subdomínios | Domínio | ✅ | ✅ | --- ## Arquitetura 🏗️ ### Arquitetura Agêntica v3.0 ``` User Input → CLI (cli.py) ├── TUI Mode → AgentLoop → Ollama → ToolExecutor → Adapters ├── Headless → AgentLoop → Single Query → Report └── Legacy → ToolExecutor Direct (no LLM) ``` ### Fluxo de Componentes ``` ┌─────────────┐ │ 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) │ └─────────────┘ ``` ### Componentes Principais 🔑 #### Camada do Agente (`src/agent/`) - **AgentLoop** 🧠: Padrão ReAct com chamada de função do Ollama - **ToolRegistry** 📋: Definições em JSON Schema para uso de ferramentas pelo LLM - **ToolExecutor** 🔧: Valida entradas, impõe stealth, faz ponte para adaptadores - **ContextManager** 📊: Sumários rolantes, previne estouro de tokens - **SessionStore** 💾: Persistência em JSON para funcionalidade salvar/carregar - **TUI** 💻: REPL com prompt_toolkit e estilo de pentest #### Camada de Orquestração (`src/orchestration/`) - **ExecutionStrategy** 🎭: Seleção de modo Docker/Nativo/Híbrido - **DockerManager** 🐳: Contêineres efêmeros com verificação SHA256 - **TaskManager** ⚡: Execução paralela com limites de recursos #### Camada de Segurança (`src/security/`) - **PluginSecurityScanner** 🛡️: Análise estática baseada em AST - **InputValidator** ✅: Prevenção de injeção, proteção contra path traversal - **SecretsManager** 🔐: Armazenamento criptografado de credenciais --- ## Segurança 🔐 ### Segurança do Agente 🛡️ - **Regras de ancoragem** impedem especulação do LLM—cite fontes ou fique em silêncio - **Imposição de modo stealth** bloqueia ferramentas de sondagem ativa quando ativado - **Validação de entrada** em todos os parâmetros das ferramentas antes da execução - **Limites de contexto** previnem injeção de prompt via estouro de tokens ### Isolamento em Contêiner 🐳🔒 - **Fixação de digest SHA256** impede adulteração de imagem ✅ - **Ciclo de vida efêmero** destrói contêineres imediatamente após a execução 🌪️ - **Limites de recursos** (768MB RAM, 50% CPU, 64 PIDs) 🚦 - **Isolamento de rede** com suporte a DNS e proxy configuráveis 🌐 - **Execução não-root** (UID/GID 65534:65534) 👥 ### Segurança de Plugins 🛡️ - **Análise estática** detecta `eval()`, `exec()`, `os.system()` e injeção de shell 🚨 - **Modelo de confiança em dois níveis** separa plugins de Ferramenta de plugins do Núcleo 🏛️ - **Declarações de capacidade** definem explicitamente as permissões necessárias 📋 --- ## Formatos de Saída 📄 O Hermes gera relatórios em múltiplos formatos via `/export`—**seus dados, do seu jeito!** 🎨 📦 **JSON** - Dados estruturados para consumo programático 📝 **Markdown** - Formato limpo e compatível com GitHub, com tabelas 🌐 **HTML** - Design responsivo com CSS embutido e estatísticas 📄 **PDF** - Formatação profissional com resumo executivo 📊 **CSV** - Formato tabular simples para importação em planilhas 🔒 **STIX 2.1** - Formato padrão da indústria para inteligência de ameaças --- ## Licença ⚖️ ### AGPL-3.0 (Community Edition) 🆓 O Hermes OSINT é licenciado sob a **GNU Affero General Public License v3.0**. **O que isso significa:** 💡 - ✅ Livre para uso pessoal e comercial - ✅ Código aberto—visualize, modifique e distribua o código - ✅ Copyleft—modificações também devem ser de código aberto sob AGPL-3.0 - ⚠️ **Uso em rede = Distribuição**—se você executar o Hermes como serviço, **deve** compartilhar seu código-fonte Veja o arquivo [LICENSE](https://github.com/expert21/hermes-osint/blob/master/LICENSE) para os termos completos. --- ## Casos de Uso 💼 🔍 **Pesquisa de Segurança** - Investigue ameaças com consultas em linguagem natural 🤝 **Due Diligence** - "Conte-me tudo sobre esta pessoa/empresa" 👣 **Análise de Pegada Digital** - Entenda a exposição da sua organização 📈 **Inteligência Competitiva** - Pesquise concorrentes de forma conversacional 🎯 **Inteligência de Ameaças** - Colete indicadores com triagem orientada por IA 📰 **Jornalismo Investigativo** - Deixe o Hermes conectar os pontos --- ## Aviso Legal e Ético ⚖️ **Apenas para atividades OSINT autorizadas.** ⚠️ Os usuários são os únicos responsáveis por obter a devida autorização, cumprir as leis aplicáveis e usar esta ferramenta de forma ética. **Usos permitidos:** ✅ - Coleta de informações publicamente disponíveis - Avaliações de segurança autorizadas - Análise de pegada digital pessoal - Conformidade com leis e regulamentos locais **Usos proibidos:** 🚫 - Assédio, perseguição ou intimidação - Tentativas de acesso não autorizado - Violações de leis de privacidade - Violações dos Termos de Serviço das plataformas **Os desenvolvedores não assumem qualquer responsabilidade pelo uso indevido desta ferramenta.** 🙅♂️ --- ## Contribuindo 🤝 Contribuições são bem-vindas! 🎉 Consulte [PLUGIN_DEVELOPMENT.md](https://github.com/expert21/hermes-osint/blob/master/PLUGIN_DEVELOPMENT.md) para diretrizes de criação de plugins e [USAGE.md](https://github.com/expert21/hermes-osint/blob/master/USAGE.md) para documentação detalhada de uso. **Tem ideias? Encontrou bugs? Quer adicionar uma ferramenta?** Abra uma issue ou envie um PR! 💪 --- ## Autor ✍️ **Isaiah Myles** ([@Expert21](https://github.com/Expert21)) *Profissional emergente de cibersegurança | Mentalidade de pentester | Construtor de ferramentas que importam* 🛠️⚡ - 🐛 **Issues**: [GitHub Issues](https://github.com/Expert21/hermes-osint/issues) - 📧 **E-mail**: [email protected] --- <div align="center"> **Hermes v3.0** 🏛️🧠 *O Analista OSINT Agêntico* --- **IA Conversacional. Ferramentas Especializadas. Inteligência Unificada.** Feito com 💪 e ☕ por alguém que acredita que OSINT deve ser **inteligente, segura e acessível**. </div>
