Criar um conector personalizado

Compatível com:

SecOps do Google SOAR

Observação:este documento pressupõe que você tenha conhecimento prático de Python e programação orientada a objetos.

Use este documento para saber como o SDK do SOAR cria integrações personalizadas para ferramentas de terceiros que podem não estar disponíveis no Content Hub. Os conectores são usados para ingerir dados de fontes que geralmente, mas nem sempre, têm algum tipo de fila de alertas. Os casos, alertas e eventos são criados na plataforma usando a interação do conector com o aplicativo Google SecOps. Um conector vai ingerir dados básicos de eventos, atribuir esses dados a um alerta e enviar o alerta para o aplicativo Google SecOps e o pipeline de tratamento de dados dele.

Observação:saiba mais sobre a biblioteca comum do TIP.

Para criar um conector personalizado, siga estas etapas gerais:

1. Crie uma classe Manager que contenha a lógica da API para a ferramenta de terceiros.
2. Crie o conector usando a IDE.

Criar o administrador

A primeira etapa para criar um conector é criar uma classe Manager que contenha toda a lógica de API necessária para a tecnologia com que você está se integrando. Por exemplo, a integração do Netskope no Google SecOps inclui um gerenciador pré-criado. Esse gerenciador contém toda a lógica necessária para interagir com a API do Netskope e pode ser usado como um modelo para sua própria implementação.

Criar o conector

No ambiente de desenvolvimento integrado, crie um conector seguindo as instruções em Como criar uma integração personalizada. O IDE vai gerar um modelo genérico que inclui comentários de código descrevendo a estrutura básica e os requisitos de um script de conector.

Embora a lógica do conector possa variar, o processo geralmente inclui estas etapas principais:

1. Use a API da ferramenta de terceiros para recuperar alertas, detecções ou eventos. No caso do Netskope, isso é tratado pelo método get_alerts(). Para evitar alertas duplicados, envie uma consulta por carimbo de data/hora e atualize-a após cada execução.
2. Crie um alerta usando a classe AlertInfo (antiga CaseInfo), atribuindo todos os campos obrigatórios.
3. Recupere e simplifique os dados de eventos associados para evitar problemas com listas e dicionários aninhados e adicione os eventos simplificados ao alerta.
4. Ordene os alertas por hora e armazene o carimbo de data/hora mais recente para usar na próxima consulta.

Observação:um alerta pode conter vários eventos. Por exemplo, as plataformas de SIEM correlacionam vários eventos em um único alarme (como o Trellix ESM) ou ofensa (como o QRadar). Em contraste, as ferramentas de detecção de endpoints geralmente geram um evento por alerta. A lógica do conector precisa refletir a estrutura da fonte de dados.

Importações e o SDK

Cada conector precisa fazer o seguinte:

• Importe a classe SiemplifyConnectorExecution de SiemplifyConnectors. Normalmente, essa classe é instanciada na função main() do conector. O script termina quando esse objeto transmite uma lista de alertas para o aplicativo Google SecOps usando o método return_package().
• Importe a classe AlertInfo de SiemplifyConnectorsDataModel. A instanciação dessa classe cria o objeto de alerta. Neste exemplo, ele é renomeado como SiemplifyAlertInfo para evitar confusão com os objetos de alerta integrados do sistema de origem (Netskope), em que essa renomeação é opcional.

O módulo SiemplifyUtils oferece métodos usados com frequência para registro em registros, processamento de formatos de dados, conversões de tempo e muito mais. Recomendamos importar output_handler, dict_to_flat e unix_now, já que eles são essenciais para a funcionalidade principal, incluindo o processamento de tempo.

A maioria dos conectores também importa a classe Manager da integração. Algumas integrações incluem mais de um gerente. Outras bibliotecas padrão do Python também podem ser importadas, dependendo do seu caso de uso.

Observação:conectores mais antigos podem usar CaseInfo de SiemplifyConnectors. Essa é a mesma classe que AlertInfo e reflete uma convenção de nomenclatura descontinuada.

Variáveis constantes

É uma boa prática declarar algumas variáveis constantes para uso posterior.

Figura 1: variáveis constantes

Exemplo de script para criar o alerta do Google SecOps

Um alerta é criado ao instanciar um objeto da classe AlertInfo, conforme discutido anteriormente. Neste exemplo, ele é renomeado como SiemplifyAlertInfo() para evitar confusão com o sistema de origem. O objeto alert_info inclui várias propriedades obrigatórias que precisam ser definidas para que o aplicativo processe o alerta corretamente. A função build_alert_info recebe um alerta do Netskope (no formato JSON bruto, recebido da API) e o objeto Siemplify como entradas. Em seguida, ele analisa o alerta do Netskope e atribui os valores relevantes aos campos "alert_info".

Essa função também usa constantes definidas anteriormente. Todas as propriedades definidas no objeto alert_info se tornam parte do objeto de alerta no aplicativo Google SecOps.

A linha 35 (na Figura 2) destaca uma parte importante desse processo: o alerta é simplificado usando o método dict_to_flat e anexado à propriedade events.

Figura 2: exemplo de script para criar um alerta

 

Um alerta pode conter vários eventos. Se for esse o caso, inclua uma lógica para processar cada evento de maneira adequada. Neste exemplo, cada alerta contém apenas um evento, então a implementação padrão é suficiente.

O método dict_to_flat é usado para simplificar a estrutura JSON bruta. Isso ajuda a evitar problemas com listas e dicionários aninhados. Os pares de chave-valor simplificados são versões ligeiramente modificadas dos originais.

Analise a lógica a seguir na Figura 2:

• display_id recebe um valor gerado aleatoriamente usando a biblioteca uuid. Os alertas do Netskope não fornecem um campo UUID, mas, se um estivesse disponível, ele poderia ser usado.
• ticket_id está definido para corresponder a display_id. Os dois campos precisam ser exclusivos por alerta no sistema. Essa exclusividade é garantida pela geração de um UUID aleatório.
• name é o nome do alerta e será exibido na GUI.
• rule_generator se refere à regra que gerou o alerta no sistema de origem. Esse campo nem sempre está presente nos dados brutos. Se ele estiver faltando, você poderá atribuir qualquer valor de string, mas não deixe o campo em branco.
• start_time e end_time representam os carimbos de data/hora do alerta. Neste exemplo, o alerta do Netskope fornece um carimbo de data/hora da época Unix, que precisa ser multiplicado por 1.000 para ser convertido em milissegundos. Esse é o formato esperado para o Google SecOps. Se a fonte usar um formato diferente, será necessário fazer a conversão. Consulte o módulo SiemplifyUtils.py para métodos úteis de conversão de tempo.
• priority: o aplicativo Google SecOps atribui uma prioridade a cada caso com base na prioridade do alerta. A API Google SecOps mapeia valores numéricos para os rótulos visuais usando o seguinte esquema, em que o valor inteiro é transmitido no conector: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}, em que o valor inteiro é o que é transmitido no conector. Por exemplo, transmitir "100" marca o alerta como Crítico na GUI. Nesse conector, uma função auxiliar adicional mapeia os valores de gravidade do Netskope para essa escala de prioridade usando a constante "SEVERITY_MAP". No entanto, como os campos de gravidade do Netskope são inconsistentes, o mapeamento exige uma lógica extra para avaliar vários campos.
• device_vendor e device_product recebem valores de constantes definidas anteriormente no script.
• environment é essencial ao usar vários ambientes no Google SecOps. Nesse caso, ele vem do objeto siemplify e se alinha ao ambiente selecionado para o conector na plataforma.
• Na linha 37 (Figura 3), o conector modifica o dicionário de eventos básicos adicionando uma nova chave, product_name, com o valor "Netskope". Isso é necessário porque os dados brutos não incluem um campo de produto consistente que possa ser usado para mapeamento e modelagem na ontologia da plataforma.

  

  Figura 3: modificação do evento de base

Exemplo de script para executar o conector

A função main contém a lógica de execução principal do conector:

• O decorador output_handler é usado para fins de depuração e não é abordado neste documento.
• A função main inclui um parâmetro opcional, is_test_run, que tem como padrão False. Como o nome sugere, esse parâmetro determina se o conector deve ingerir alertas em produção ou ser executado no modo de teste na guia Teste de conector do aplicativo.

Revise o detalhamento da lógica de execução principal por linha de script:

Figura 3: modificação do evento de base

• As linhas 56 e 57 inicializam duas listas vazias usadas durante a execução.
• Na linha 58, a classe SiemplifyConnectorExecution instancia o objeto siemplify. Esse objeto gerencia a maior parte do comportamento de tempo de execução do conector.
• Na linha 61, uma instância de Lista de permissões do conector é criada. Embora não seja usado neste conector, ele é comum em outros conectores e não é abordado neste guia.
• Nas linhas 67 a 69, as variáveis são definidas para parâmetros do conector, como credenciais de autenticação ou configurações de configuração.
• Na linha 71, ele cria uma instância do objeto NetskopeManager e transmite os parâmetros relevantes para permitir uma autenticação bem-sucedida. A lógica interna do gerenciador que processa a autenticação não é mostrada neste exemplo.
• Na linha 73, ele recupera um carimbo de data/hora de um arquivo local criado durante execuções anteriores do conector. Esse carimbo de data/hora é usado para evitar o reprocessamento dos mesmos alertas.
• Nas linhas 74 e 75, ele processa o caso em que o conector está sendo executado pela primeira vez e o carimbo de data/hora ainda não foi definido (por exemplo, quando o padrão é "0"). Como o Netskope exige o horário da época Unix e não aceita "0" como um horário de início válido, a função "unix_now" é usada para recuperar a hora atual em milissegundos. Esse valor é dividido por "1.000" para ser convertido em segundos da época Unix. Os horários de início e término resultantes são transmitidos ao método "get_alerts" no gerenciador. Embora muitas APIs aceitem apenas um horário de início, a API do Netskope exige horários de início e de término para consultas de alertas com base em tempo.
Observação:o processamento de hora e carimbo de data/hora é um dos aspectos mais complexos da criação de um conector. Diferentes sistemas de terceiros retornam carimbos de data/hora em vários formatos, e alguns podem não oferecer suporte a consultas com base no mesmo formato que retornam. É essencial ter um bom entendimento da API do sistema de origem.
• Na linha 77, ele recupera uma lista de alertas do Netskope. Se o conector estiver no modo de teste, apenas o último alerta na lista será selecionado (linhas 79 a 80).

Lógica de estouro

Em seguida, o conector itera pelos alertas recuperados e cria um alerta de cada um usando a função build_alert_info definida anteriormente. Ele anexa cada alerta à lista all_alerts, inicializada anteriormente. A próxima parte da lógica do conector processa o transbordamento.
O estouro é um mecanismo de limite que impede que muitos alertas sejam ingeridos em um curto período, principalmente quando eles compartilham o mesmo ambiente, produto e gerador de regras. Embora não seja obrigatório, recomendamos implementar a lógica de estouro como uma prática recomendada para evitar a degradação da performance.

Revise o detalhamento da lógica de estouro por linha de script na Figura 4:

• Nas linhas 104 a 105, se um alert não for classificado como estouro, ele será anexado à lista de alertas a serem ingeridos.



Figura 4: mecanismo de estouro.

Como encerrar a execução do conector

Se o conector não estiver em execução no modo de teste, o carimbo de data/hora precisará ser atualizado para refletir o último alerta recuperado. Isso garante que os mesmos alertas não sejam ingeridos novamente durante o próximo ciclo de execução. A lista all_alerts é classificada por carimbo de data/hora para que até mesmo alertas excedidos contribuam para determinar o carimbo de data/hora mais recente.

Revise o detalhamento da lógica de execução do conector por linha de script na Figura 5:

• Na linha 126, a lista de alertas não excedidos é enviada ao aplicativo, onde os alertas são criados e mostrados na GUI.
• Nas linhas 128 a 131, eles determinam se o conector está sendo executado no modo de teste. Os argumentos do sistema transmitidos pelo aplicativo, como ao clicar em Executar conector uma vez na guia Teste, são usados para fazer essa determinação.
  

  

  Figura 5: como encerrar a execução do conector

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.