Crie um conector personalizado

Suportado em:

Use este documento para saber como o SDK SOAR cria integrações personalizadas para ferramentas de terceiros que podem não estar disponíveis no centro de conteúdo. Os conetores são usados para carregar dados de origens de dados que, normalmente, mas nem sempre, têm algum tipo de fila de alertas. Os registos, os alertas e os eventos são criados na plataforma através da interação do conector com a aplicação Google SecOps. Um conetor vai carregar dados de eventos base, atribuir esses dados a um alerta e, em seguida, enviar o alerta para a aplicação Google SecOps e o respetivo pipeline de tratamento de dados.

Para criar um conector personalizado, siga estes passos gerais:

  1. Crie uma classe Manager que contenha a lógica da API para a ferramenta de terceiros.
  2. Crie o conetor através do IDE.

Crie o gestor

O primeiro passo na criação de um conetor é criar uma classe Manager que contenha toda a lógica da API necessária para a tecnologia com a qual está a fazer a integração. Por exemplo, a integração do Netskope no Google SecOps inclui um gestor pré-criado. Este gestor contém toda a lógica necessária para interagir com a API Netskope e pode ser usado como um modelo para a sua própria implementação.

Crie o conetor

No IDE, crie um novo conetor seguindo as instruções em Criar uma integração personalizada. O IDE gera um modelo genérico que inclui comentários de código que descrevem a estrutura básica e os requisitos de um script de conector.

Embora a lógica do conector possa variar, o processo geralmente inclui estes passos essenciais:

  1. Use a API da ferramenta de terceiros para obter alertas, deteções ou eventos. No caso do Netskope, isto é processado através do método get_alerts(). Para garantir que os alertas não são duplicados, envie uma consulta por indicação de tempo e atualize-a após cada execução.
  2. Crie um alerta com a classe AlertInfo (anteriormente CaseInfo), atribuindo todos os campos obrigatórios
  3. Recupere e reduza os dados de eventos associados para evitar problemas com listas e dicionários aninhados e, em seguida, anexe os eventos reduzidos ao alerta.
  4. Ordene os alertas por hora e armazene a data/hora mais recente para usar na consulta seguinte.

Importações e o SDK

Todos os conetores têm de fazer o seguinte:

  • Importe a turma SiemplifyConnectorExecution de SiemplifyConnectors. Normalmente, esta classe é instanciada na função main() do conetor. O script termina quando este objeto transmite uma lista de alertas à aplicação Google SecOps através do método return_package().
  • Importe a turma AlertInfo de SiemplifyConnectorsDataModel. A instanciação desta classe cria o objeto de alerta. Neste exemplo, o nome é alterado para SiemplifyAlertInfo para evitar confusão com os objetos de alerta incorporados do sistema de origem (Netskope), onde esta alteração do nome é opcional.

O módulo SiemplifyUtils fornece métodos usados frequentemente para registar, processar formatos de dados, conversões de tempo e muito mais. Recomendamos que importe output_handler, dict_to_flat e unix_now, uma vez que são essenciais para a funcionalidade principal, incluindo o processamento de tempo.

A maioria dos conetores também importa a classe Manager da integração. Algumas integrações incluem mais do que um gestor. Também é possível importar bibliotecas Python padrão adicionais, consoante o seu exemplo de utilização.

Variáveis constantes

É uma boa prática declarar algumas variáveis constantes para utilização posterior.

custconnector2
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 abordado anteriormente. Neste exemplo, o nome foi alterado para SiemplifyAlertInfo() para evitar confusões com o sistema de origem. O objeto alert_info inclui várias propriedades obrigatórias que têm de ser definidas para que a aplicação processe corretamente o alerta. A função build_alert_info recebe um alerta do Netskope (no formato JSON não processado, recebido da API) e o objeto Siemplify como entradas. Em seguida, analisa o alerta do Netskope e atribui os valores relevantes aos campos `alert_info`.

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

A linha 35 (na Figura 2) realça uma parte importante deste processo: o alerta é reduzido usando o método dict_to_flat e, em seguida, anexado à propriedade events.

custconnector3
Figura 2: exemplo de script para criar um alerta
 

Um alerta pode conter vários eventos. Se for esse o caso, tem de incluir lógica para processar cada evento de forma adequada. Neste exemplo, cada alerta contém apenas um evento, pelo que a implementação predefinida é suficiente.

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

Reveja a seguinte lógica na Figura 2:

  • display_id é atribuído um valor gerado aleatoriamente através da biblioteca uuid. Os alertas do Netskope não fornecem um campo UUID, mas, se estivesse disponível, poderia ser usado em alternativa.
  • ticket_id está definido para corresponder a display_id. Ambos os campos têm de ser exclusivos por alerta no sistema. Esta exclusividade é garantida através da geração de um UUID aleatório.
  • name é o nome do alerta e é apresentado na GUI.
  • rule_generator refere-se à regra que gerou o alerta no sistema de origem. Este campo pode nem sempre estar presente nos dados não processados. Se estiver em falta, pode atribuir qualquer valor de string, mas não pode ficar vazio.
  • start_time e end_time representam as indicações de tempo do alerta. Neste exemplo, o alerta do Netskope fornece uma indicação de tempo de época Unix, que tem de ser multiplicada por 1000 para a converter em milissegundos. Este é o formato esperado para o Google SecOps. Se a origem usar um formato diferente, tem de o converter. Consulte o SiemplifyUtils.pymódulo para ver métodos úteis de conversão de tempo.
  • priority: a aplicação Google SecOps atribui uma prioridade a cada registo com base na prioridade do respetivo alerta. A API Google SecOps mapeia valores numéricos para as etiquetas visuais através do seguinte esquema, em que o valor inteiro é transmitido no conetor: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100} em que o valor inteiro é o que é transmitido no conetor. Por exemplo, a transmissão de `100` marca o alerta como Crítico na GUI. Neste conetor, uma função auxiliar adicional mapeia os valores de gravidade do Netskope para esta escala de prioridade através da constante `SEVERITY_MAP`. No entanto, uma vez que os campos de gravidade do Netskope são inconsistentes, o mapeamento requer uma lógica adicional para avaliar vários campos.
  • device_vendor e device_product são atribuídos a valores de constantes definidos anteriormente no script.
  • environment é fundamental quando usa vários ambientes no Google SecOps. Neste caso, provém do objeto siemplify e está alinhado com o ambiente selecionado para o conector na plataforma.
  • Na linha 37 (Figura 3), o conector modifica o dicionário de eventos base adicionando uma nova chave, product_name, com o valor "Netskope". Isto é necessário porque os dados não processados não incluem um campo de produto consistente que possa ser usado para mapeamento e modelagem na ontologia da plataforma.
    custconnector4
    Figura 3: modificar o evento base

Exemplo de guião para executar o conetor

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

  • 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 predefinição False. Como o nome indica, este parâmetro determina se o conetor deve carregar alertas em produção ou ser executado no modo de teste a partir do separador Testes de conetores na aplicação.

Reveja a discriminação da lógica de execução principal por linha do script:

custconnector4
Figura 3: modificar o evento 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. Este objeto gere a maioria do comportamento de tempo de execução do conector.
  • Na linha 61, é criada uma instância de Connector Allowlist. Embora não seja usado neste conetor, é usado frequentemente noutros conetores e não é abordado neste guia.
  • Nas linhas 67 a 69, são definidas variáveis para parâmetros do conetor, como credenciais de autenticação ou definições de configuração.
  • Na linha 71, instancia o objeto NetskopeManager e transmite os parâmetros relevantes para permitir uma autenticação bem-sucedida. A lógica do gestor interno que processa a autenticação não é apresentada neste exemplo.
  • Na linha 73, obtém uma data/hora de um ficheiro local criado durante execuções anteriores do conetor. Esta data/hora é usada para evitar o reprocessamento dos mesmos alertas.
  • Nas linhas 74 e 75, processa o caso em que o conector está a ser executado pela primeira vez e a data/hora ainda não está definida (por exemplo, quando é predefinida como "0"). Uma vez que o Netskope requer a hora de época Unix e não aceita "0" como uma hora de início válida, a função `unix_now` é usada para obter a hora atual em milissegundos. Este valor é dividido por "1000" para o converter em segundos da época Unix. As horas de início e fim resultantes são, em seguida, transmitidas ao método `get_alerts` no gestor. Embora muitas APIs aceitem apenas uma hora de início, a API Netskope requer horas de início e de fim para consultas de alertas baseadas no tempo.
  • Na linha 77, obtém uma lista de alertas do Netskope. Se o conetor estiver a ser executado no modo de teste, apenas o último alerta na lista é selecionado (linhas 79 a 80).

Lógica de overflow

Em seguida, o conetor itera os alertas obtidos e cria um alerta a partir de cada alerta através da função build_alert_info definida anteriormente. Acrescenta cada alerta à lista all_alerts, inicializada anteriormente. A parte seguinte da lógica do conector processa o overflow.
O excesso é um mecanismo de limite que impede a ingestão de demasiados alertas num curto período, especialmente quando os alertas partilham o mesmo ambiente, produto e gerador de regras. Embora não seja obrigatório, recomendamos a implementação da lógica de overflow como prática recomendada para evitar a degradação do desempenho.

Reveja a análise detalhada da lógica de overflow por linha de script na Figura 4:

  • Nas linhas 104 a 105, se um alert não for classificado como excesso, é anexado à lista de alertas a carregar.

    • custconnector5
    Figura 4: mecanismo de excesso.

Terminar a execução do conetor

Se o conetor não estiver a ser executado no modo de teste, a data/hora tem de ser atualizada para refletir o último alerta obtido. Isto garante que os mesmos alertas não são novamente carregados durante o ciclo de execução seguinte. A lista all_alerts é ordenada por data/hora para que mesmo os alertas em excesso contribuam para determinar a data/hora mais recente.

Reveja a discriminação da lógica de execução do conetor por linha de script na Figura 5:

  • Na linha 126, a lista de alertas sem overflow é enviada para a aplicação, onde os alertas são criados e apresentados na GUI.
  • Nas linhas 128 a 131, determinam se o conector está a ser executado no modo de teste. Os argumentos do sistema transmitidos pela aplicação, como quando clica em Executar conetor uma vez no separador Testes, são usados para fazer esta determinação.
    custconnector6
    Figura 5: terminar a execução do conector

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