Elasticsearch Security Solution

Um servidor Elasticsearch focado em segurança e análise de ameaças. Requer uma licença válida do Elasticsearch (trial, platinum ou enterprise) para conexão.

GitHub
8

Documentação

Servidor MCP Elasticsearch

npm version Downloads Ask DeepWiki

Solução Aprimorada do Servidor MCP Elasticsearch - Foco em Segurança e Análise de Ameaças

Esta é uma solução profissional focada em segurança, mantida por TocharianOU. Ela permite interação abrangente com todas as APIs do Elasticsearch, especificamente otimizada para análise de segurança, detecção de ameaças e investigação de incidentes. Os recursos incluem monitoramento de segurança avançado, detecção de anomalias, caça a ameaças, análise de causa raiz e capacidades abrangentes de auditoria.

Principais Recursos de Segurança:

  • Detecção de ameaças em tempo real e monitoramento de segurança
  • Aprendizado de máquina avançado para detecção de anomalias
  • Análise de causa raiz e rastreamento de cadeia de ataques
  • Investigação de incidentes de segurança e perícia digital
  • Monitoramento de conformidade e relatórios de auditoria

Nota: Esta solução requer uma licença válida do Elasticsearch (trial, platinum ou enterprise) e é projetada para profissionais de segurança, equipes SOC e analistas de ameaças.

Conecte-se diretamente aos seus dados do Elasticsearch a partir de qualquer Cliente MCP (como Claude Desktop) usando o Model Context Protocol (MCP). Interaja com seus dados de segurança do Elasticsearch por meio de consultas em linguagem natural para análise avançada de ameaças e resposta a incidentes.

Pré-requisitos

  • Uma instância do Elasticsearch
  • Uma licença válida do Elasticsearch (trial, platinum ou enterprise) é obrigatória.
  • Credenciais de autenticação do Elasticsearch (chave de API ou nome de usuário/senha)
  • Cliente MCP (ex.: Claude Desktop) ou cliente HTTP para acesso remoto

⚠️ Este projeto requer que seu cluster Elasticsearch tenha uma licença válida. Se você não tiver uma licença, pode ativar uma licença trial conforme mostrado abaixo.

Suporte Multi-versão do Elasticsearch

Suporta automaticamente Elasticsearch 5.x - 9.x com detecção inteligente de versão:

VersãoStatusClienteObservações
ES 5.x✅5.6.22EOL - Apenas ferramentas básicas
ES 6.x✅6.8.8EOL - ILM disponível (6.6+)
ES 7.x✅7.17.14LTS - Recursos completos
ES 8.x✅8.19.1Recomendado - Recursos mais recentes, ES|QL (8.11+)
ES 9.x+✅Fallback automáticoPronto para o futuro

Principais Recursos:

  • Detecção automática de versão - Nenhuma configuração manual necessária
  • Seleção inteligente de cliente - Carrega o cliente certo para a sua versão do ES
  • Recursos adaptativos - Desativa ferramentas não suportadas (ex.: Data Streams em ES < 7.9, ES|QL em ES < 8.11)
  • Otimizações específicas de versão - Lida com diferenças de API de forma transparente

O que acontece:

Connect → Detect ES version → Load matching client → Register compatible tools

Conexão SSL/TLS

Para conectar ao Elasticsearch com um certificado autoassinado ou em ambiente de teste, você pode definir a seguinte variável de ambiente:

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ Isso desativa a validação de certificado SSL do Node.js. Use apenas em ambientes de desenvolvimento ou teste. Para produção, sempre use um certificado CA confiável.

Instalação e Configuração

  1. Inicie uma Conversa
    • Abra uma nova conversa no seu Cliente MCP
    • O servidor MCP deve conectar automaticamente
    • Agora você pode fazer perguntas sobre seus dados do Elasticsearch

Opções de Configuração

O Servidor MCP Elasticsearch suporta as seguintes opções de configuração:

Configuração do Elasticsearch

Variável de AmbienteDescriçãoObrigatório
ES_URLURL da sua instância do ElasticsearchSim
ES_API_KEYChave de API do Elasticsearch para autenticaçãoNão
ES_USERNAMENome de usuário do Elasticsearch para autenticação básicaNão
ES_PASSWORDSenha do Elasticsearch para autenticação básicaNão
ES_CA_CERTCaminho para certificado CA personalizado para SSL/TLSNão
NODE_TLS_REJECT_UNAUTHORIZEDDefina como 0 para desativar a validação de certificado SSLNão

Configuração do Modo de Transporte (NOVO na v0.3.0)

Variável de AmbienteDescriçãoPadrãoValores
MCP_TRANSPORTSeleção do modo de transportestdiostdio, http
MCP_HTTP_PORTPorta do servidor HTTP (ao usar transporte HTTP)30001-65535
MCP_HTTP_HOSTHost do servidor HTTP (ao usar transporte HTTP)localhostQualquer host válido

Detalhes dos Modos de Transporte:

  • Modo Stdio (padrão): Para Claude Desktop e clientes MCP locais
  • Modo HTTP Streamable: Roda como um servidor HTTP autônomo para acesso remoto, integração de API e aplicações web

Início Rápido

Opção 1: Instalação via NPM (Recomendado)

  1. Instale globalmente via NPM

    npm install -g @tocharianou/elasticsearch-mcp

  2. Execute diretamente

    npx @tocharianou/elasticsearch-mcp

Opção 2: Release no GitHub (Pacote Autônomo)

  1. Baixe o pacote de release

    • Vá para GitHub Releases
    • Baixe o arquivo mais recente .tar.gz e seus arquivos de checksum (.sha256 e .sha512)

  2. Verifique a integridade do pacote

    shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256
# Should output: elasticsearch-mcp-v*.tar.gz: OK

  3. Extraia e use

    mkdir elasticsearch-mcp && cd elasticsearch-mcp
tar -xzf ../elasticsearch-mcp-v*.tar.gz

# Run with your Elasticsearch credentials
ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js

Opção 3: Instalação a partir do Código-fonte

  1. Clone o repositório

    git clone https://github.com/TocharianOU/elasticsearch-mcp.git
cd elasticsearch-mcp

  2. Instale as Dependências

    npm install

  3. Compile o Projeto

    npm run build

  4. Configure o App do Claude Desktop

    • Abra o Claude Desktop App
    • Vá para Configurações > Desenvolvedor > Servidores MCP
    • Clique em Edit Config e adicione um novo Servidor MCP com a seguinte configuração:

    Para Instalação via NPM:

    {
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": [
        "@tocharianou/elasticsearch-mcp"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

    Para Instalação a partir do Código-fonte:

    {
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "node",
      "args": [
        "/path/to/your/elasticsearch-mcp/dist/index.js"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

  5. Depuração com MCP Inspector

    ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector

    Isso iniciará o MCP Inspector, permitindo depurar e analisar solicitações. Você deve ver:

    Starting MCP inspector...
Proxy server listening on port 3000

MCP Inspector is up and running at http://localhost:5173

Método 3: Modo HTTP Streamable (NOVO na v0.3.0)

Execute o servidor como um serviço HTTP autônomo para acesso remoto e integração de API:

# Start HTTP server (default port 3000)
MCP_TRANSPORT=http \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

# Or with custom port and host
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

Recursos do Modo HTTP Streamable:

  • Expõe o servidor MCP no endpoint http://host:port/mcp
  • Verificação de saúde disponível em http://host:port/health
  • Gerenciamento de conexão baseado em sessão
  • Suporta tanto POST (solicitações JSON-RPC) quanto GET (streams SSE)
  • Compatível com qualquer cliente HTTP ou SDK MCP

Exemplo de uso com cliente HTTP:

// Initialize connection
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'my-client', version: '1.0.0' }
    },
    id: 1
  })
});

const sessionId = response.headers.get('mcp-session-id');

// Subsequent requests include session ID
const toolsResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/list',
    params: {},
    id: 2
  })
});

// Call a tool (e.g., list_indices)
const indicesResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'list_indices',
      arguments: {}
    },
    id: 3
  })
});

Ferramentas Disponíveis

FerramentaDescriçãoVersão Mínima
list_indicesLista índices com filtro de padrão, filtro de saúde, ordenação e resumo ciente de tokensES 5.x+
get_mappingsObtém mapeamentos de campos com modos plano/árvore/bruto, filtragem de campos e comparação multi-índiceES 5.x+
es_searchPesquisa completa com Query DSL e realce automático em campos de texto/vetorES 5.x+
execute_es_apiExecuta qualquer endpoint REST do ES diretamente (GET/POST/PUT/DELETE/HEAD)ES 5.x+
get_shardsInformações de shards com análise de saúde, detecção de problemas e recomendaçõesES 5.x+
list_data_streamsLista e analisa Data Streams com informações ILM e detalhes dos índices de apoioES 7.9+
esql_queryExecuta consultas ES|QL baseadas em pipes com saída tabular e suporte a parâmetrosES 8.11+

Ferramentas não suportadas pela versão do seu cluster são automaticamente ignoradas na inicialização.

Ferramenta de Consulta ES|QL (esql_query)

ES|QL é a linguagem de consulta moderna baseada em pipes do Elasticsearch, ideal para análises e exploração de dados sem complexo JSON DSL.

Exemplos de consultas:

FROM logs-* | WHERE level == "error" | STATS count = COUNT(*) BY service | SORT count DESC | LIMIT 20
FROM metrics-* | WHERE @timestamp > NOW() - 1 hour | STATS avg_cpu = AVG(cpu.usage) BY host.name
FROM auditbeat-* | WHERE event.action == "user_login" AND event.outcome == "failure" | LIMIT 50

Parâmetros:

  • query — a string ES|QL (obrigatório)
  • params — parâmetros posicionais que substituem marcadores ? (opcional)
  • include_types — incluir informações de tipo de coluna na saída (opcional, padrão false)
  • break_token_rule — ignorar limite de tokens para resultados grandes (opcional, padrão false)

Registrado automaticamente apenas em clusters ES 8.11+.

Contribuindo

Aceitamos contribuições da comunidade! Para detalhes sobre como contribuir, consulte as Diretrizes de Contribuição.

Como Funciona

  1. O Cliente MCP analisa sua solicitação e determina quais operações do Elasticsearch são necessárias.
  2. O servidor MCP se comunica com o ES.
  3. O Cliente MCP processa os resultados e os apresenta em um formato amigável, incluindo realces, resumos de agregações e insights de anomalias.

Exemplos de Análise de Segurança

[!TIP] Aqui estão consultas focadas em segurança que você pode experimentar com seu Cliente MCP.

Detecção de Ameaças:

  • "Analisar tentativas de ataque de força bruta nas últimas 24 horas"
  • "Detectar comportamento anormal de login e endereços IP suspeitos no sistema"
  • "Identificar padrões de ataque de injeção SQL e solicitações maliciosas"
  • "Descobrir assinaturas de ataques DDoS e anomalias de tráfego em fluxos de rede"

Análise de Causa Raiz:

  • "Rastrear a cadeia completa de ataque e o escopo do impacto para incidentes de segurança específicos"
  • "Analisar causas raiz e caminhos de propagação de falhas do sistema"
  • "Identificar fontes de violação de dados e informações sensíveis envolvidas"
  • "Investigar incidentes de abuso de privilégios de usuário com linha do tempo e registros de operações"

Inteligência de Ameaças:

  • "Criar modelos de aprendizado de máquina para detectar ataques de dia zero e ameaças desconhecidas"
  • "Estabelecer linhas de base comportamentais e identificar atividades que se desviam dos padrões normais"
  • "Analisar níveis de ameaça e histórico de ataques de domínios e endereços IP maliciosos"
  • "Detectar características comportamentais e padrões de ataque de Ameaças Persistentes Avançadas (APT)"

Monitoramento em Tempo Real:

  • "Monitorar ameaças ativas e ataques em andamento no sistema atual"
  • "Detectar padrões anormais de acesso a dados e comportamentos de escalonamento de privilégios"
  • "Descobrir comunicações de rede suspeitas e atividades de exfiltração de dados"
  • "Identificar causas de segurança de consumo anormal de recursos do sistema e degradação de desempenho"

Melhores Práticas de Segurança

[!WARNING] Evite usar privilégios de administrador de cluster. Crie chaves de API dedicadas com escopo limitado e aplique controle de acesso fino no nível de índice para impedir acesso não autorizado a dados.

Verificação de Integridade do Pacote

Ao baixar pacotes de release, sempre verifique os checksums para garantir a integridade:

# Verify SHA256 checksum
shasum -a 256 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha256

# Verify SHA512 checksum
shasum -a 512 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha512

Isso protege contra:

  • Downloads corrompidos
  • Pacotes adulterados
  • Ataques man-in-the-middle

Controle de Acesso ao Elasticsearch

Você pode criar uma chave de API dedicada do Elasticsearch com permissões mínimas para controlar o acesso aos seus dados:

{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

Licença

Este projeto está licenciado sob a Licença Apache 2.0.

Solução de Problemas

  • Certifique-se de que sua configuração MCP está correta.
  • Verifique se a URL do seu Elasticsearch está acessível a partir da sua máquina.
  • Verifique se suas credenciais de autenticação (chave de API ou nome de usuário/senha) têm as permissões necessárias.
  • Se estiver usando SSL/TLS com um CA personalizado, verifique se o caminho do certificado está correto e se o arquivo é legível.
  • Observe a saída do terminal para ver mensagens de erro.

Se encontrar problemas, sinta-se à vontade para abrir uma issue no repositório do GitHub.

Executando com uma Licença Trial

Se o seu cluster Elasticsearch não tiver uma licença válida, você pode ativar uma licença trial de 30 dias com o seguinte comando:

curl -X POST -u elastic:your_password \
  -k "https://your-es-host:9200/_license/start_trial?acknowledge=true"
  • Substitua your_password e your-es-host pelas suas credenciais e host reais.
  • Isso habilitará todos os recursos por 30 dias.

Nota: Este projeto não iniciará se o seu cluster não tiver uma licença válida (trial, platinum, enterprise etc.).