Usar o Logstash para transmitir logs com a API de Coleta de Dados HTTP (herdada)

  • Artigo

Importante

A ingestão de dados usando o plug-in de saída Logstash está atualmente em visualização pública. Esse recurso é fornecido sem um Contrato de Nível de Serviço e não é recomendado para cargas de trabalho de produção. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Observação

Uma versão mais recente do plug-in Logstash pode encaminhar logs de fontes de dados externas para tabelas personalizadas e padrão usando a API baseada em DCR. O novo plug-in permite controle total sobre o esquema de saída, incluindo a configuração dos nomes e tipos de coluna.

Usando o plug-in de saída do Microsoft Sentinel para o mecanismo de coleta de dados Logstash, é possível enviar os logs desejados por meio do Logstash diretamente para o espaço de trabalho do Log Analytics no Microsoft Sentinel. Os logs serão enviados para uma tabela personalizada que você define usando o plug-in de saída. Essa versão do plug-in usa a API de Coleta de Dados HTTP.

Para saber mais sobre como trabalhar com o mecanismo de coleta de dados do Logstash, consulte Introdução ao Logstash.

Visão geral

Arquitetura e plano de fundo

Diagram of the Logstash architecture.

O mecanismo Logstash é composto por três componentes:

  • Plug-ins de entrada: coleção personalizada de dados de várias fontes.
  • Plug-ins de filtro: manipular e normalizar dados de acordo com os critérios especificados.
  • Plug-ins de saída: envio personalizado de dados coletados e processados para vários destinos.

Observação

  • A Microsoft dá suporte apenas ao plug-in de saída Logstash fornecido pelo Microsoft Sentinel aqui. A versão atual deste plug-in é a v1.0.0, lançada em 25-08-2020. Você pode abrir um tíquete de suporte para quaisquer problemas relacionados ao plug-in de saída.

  • Ele não dá suporte a plug-ins de saída de terceiros para o Microsoft Sentinel ou qualquer outro plug-in ou componente do Logstash de qualquer tipo.

  • O plug-in de saída do Logstash do Microsoft Sentinel só dá suporte ao Logstash versões 7.0 a 7.17.10 e versões 8.0 a 8.9 e 8.11. Se você usar o Logstash 8, recomendamos desabilitar o ECS no pipeline.

O plug-in de saída do Microsoft Sentinel para o Logstash envia dados formatados em JSON para o workspace do Log Analytics, usando a API REST do coletor de dados HTTP do Log Analytics. Os dados são ingeridos em logs personalizados.

Implantar o plug-in de saída do Microsoft Sentinel no Logstash

Etapa 1: Instalação

O plug-in de saída do Microsoft Sentinel está disponível na coleção do Logstash.

Etapa 2: Configuração

Use as informações no documento da Logstash Estrutura de um arquivo de configuração e adicione o plug-in de saída do Microsoft Sentinel à configuração com as chaves e os valores a seguir. (A sintaxe apropriada do arquivo de configuração é mostrada após a tabela.)

Nome do campo Tipo de dados Descrição
workspace_id string Insira o GUID da ID do worksapce (consulte a Dica).
workspace_key string Insira o GUID da chave primária do workspace (consulte a dica).
custom_log_table_name string Defina o nome da tabela na qual os logs serão ingeridos. Somente pode ser configurado um nome de tabela por plug-in de saída. A tabela de log será exibida no Microsoft Sentinel em Logs, em Tabelas na categoria Logs personalizados, com um sufixo _CL.
endpoint string Campo opcional. Por padrão, esse é o ponto de extremidade do Log Analytics. Use este campo para definir um ponto de extremidade alternativo.
time_generated_field string Campo opcional. Essa propriedade substitui o campo padrão TimeGenerated no log Analytics. Insira o nome do campo de carimbo de data/hora na fonte de dados. Os dados no campo devem estar de acordo com o formato ISO 8601 (YYYY-MM-DDThh:mm:ssZ)
key_names matriz Insira uma lista de campos de esquema de saída do Log Analytics. Cada item de lista deve ser colocado entre aspas simples, os itens separados por vírgulas e a lista inteira entre colchetes. Consulte o exemplo a seguir.
plugin_flush_interval número Campo opcional. Usado para definir o intervalo máximo (em segundos) entre as transmissões de mensagem para o Log Analytics. O padrão é 5.
amount_resizing booleano True ou false. Habilitar ou desabilitar o mecanismo de dimensionamento automático, que ajusta o tamanho do buffer de mensagens de acordo com o volume de dados de log recebidos.
max_items número Campo opcional. Aplica-se somente se amount_resizing estiver definido como "falso". Use para definir um limite no tamanho do buffer de mensagem (em registros). O padrão é 2000.
azure_resource_id string Campo opcional. Define a ID do recurso do Azure onde os dados residem.
O valor da ID do recurso será especialmente útil se for usado o RBAC de contexto de recurso para fornecer acesso apenas a dados específicos.

Dica

  • É possível encontrar a ID do workspace e a chave primária no recurso do workspace, em Gerenciamento de agentes.
  • No entanto, como ter credenciais e outras informações confidenciais armazenadas em texto não criptografado em arquivos de configuração não está alinhado com as melhores práticas de segurança, é altamente recomendável usar o Repositório de chaves do Logstash para incluir com segurança a ID do workspace e a chave primária do workspace na configuração. Confira a Documentação sobre o Elastic para obter as instruções.

Exemplos de configuração

A seguir algumas configurações de exemplo que usam diferentes opções.

  • Uma configuração básica que usa um pipe de entrada filebeat:

      input {
      beats {
          port => "5044"
      }
  }
  filter {
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
        workspace_id => "<your workspace id>"
        workspace_key => "<your workspace key>"
        custom_log_table_name => "tableName"
      }
  }

  • Uma configuração básica que usa um pipe de entrada tcp:

      input {
      tcp {
          port => "514"
          type => syslog #optional, will effect log type in table
      }
  }
  filter {
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
        workspace_id => "<your workspace id>"
        workspace_key =>  "<your workspace key>"
        custom_log_table_name => "tableName"
      }
  }

  • Uma configuração avançada:

      input {
      tcp {
          port => 514
          type => syslog
      }
  }
  filter {
      grok {
          match => { "message" => "<%{NUMBER:PRI}>1 (?<TIME_TAG>[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}T[0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2})[^ ]* (?<HOSTNAME>[^ ]*) %{GREEDYDATA:MSG}" }
      }
  }
  output {
      microsoft-logstash-output-azure-loganalytics {
          workspace_id => "<WS_ID>"
          workspace_key => "${WS_KEY}"
          custom_log_table_name => "logstashCustomTable"
          key_names => ['PRI','TIME_TAG','HOSTNAME','MSG']
          plugin_flush_interval => 5
      }
  }

  • Uma configuração mais avançada para analisar um carimbo de data/hora personalizado e uma cadeia de caracteres JSON a partir de dados de texto não estruturados e registrar um conjunto selecionado de campos no Log Analytics com o carimbo de data/hora extraído:

      # Example log line below:
  # Mon Nov 07 20:45:08 2022: { "name":"_custom_time_generated", "origin":"test_microsoft", "sender":"test@microsoft.com", "messages":1337}
  # take an input
  input {
      file {
          path => "/var/log/test.log"
      }
  }
  filter {
  # extract the header timestamp and the Json section
      grok {
          match => {
              "message" => ["^(?<timestamp>.{24}):\s(?<json_data>.*)$"]
          }
      }
  # parse the extracted header as a timestamp
  date {
      id => 'parse_metric_timestamp'
          match => [ 'timestamp', 'EEE MMM dd HH:mm:ss yyyy' ]
          timezone => 'Europe/Rome'
          target => 'custom_time_generated'
      }
  json {
      source => "json_data"
      }
  }
  # output to a file for debugging (optional)
  output {
      file {
          path => "/tmp/test.txt"
          codec => line { format => "custom format: %{message} %{custom_time_generated} %{json_data}"}
      }
  }
  # output to the console output for debugging (optional)
  output {
      stdout { codec => rubydebug }
  }
  # log into Log Analytics
  output {
      microsoft-logstash-output-azure-loganalytics {
          workspace_id => '[REDACTED]'
          workspace_key => '[REDACTED]'
          custom_log_table_name => 'RSyslogMetrics'
          time_generated_field => 'custom_time_generated'
          key_names => ['custom_time_generated','name','origin','sender','messages']
      }
  }

    Observação

    Visite o plug-in de saída do repositório GitHub para saber mais sobre trabalhos internos, configurações e configurações de desempenho.

Etapa 3: Reiniciar o Logstash

Etapa 4: Exibir logs de entrada no Microsoft Sentinel

  1. Verifique se as mensagens estão sendo enviadas para o plug-in de saída.

  2. No menu de navegação do Azure Sentinel, clique em Logs. No título Tabelas, expanda a categoria Logs personalizados. Localize e clique no nome da tabela especificada (com um sufixo _CL) na configuração.

    Screenshot of log stash custom logs.

  3. Para ver os registros na tabela, consulte a tabela usando o nome da tabela como o esquema.

    Screenshot of a log stash custom logs query.

Monitorar logs de auditoria do plug-in de saída

Para monitorar a conectividade e a atividade do plug-in de saída do Microsoft Sentinel, habilite o arquivo de log Logstash apropriado. Consulte o documento Layout do diretório Logstash para o local do arquivo de log.

Se não for exibido nenhum dado nesse arquivo de log, gere e envie alguns eventos localmente (por meio dos plug-ins de entrada e de filtro) para verificar se o plug-in de saída está recebendo dados. O Microsoft Sentinel dará suporte apenas a problemas relacionados ao plug-in de saída.

Próximas etapas

Neste documento, você aprendeu a usar o Logstash para conectar fontes de dados externas ao Microsoft Sentinel. Para saber mais sobre o Microsoft Sentinel, confira os seguintes artigos: