Funções de transformação personalizadas e operadores lógicos

Compatível com:

Google SecOps SOAR

Observação: esse recurso é coberto pelos Termos de produtos pré-GA dos Termos específicos de serviço do Google Security Operations. Os recursos pré-GA podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as diretrizes do serviço de suporte técnico do Google SecOps e os Termos específicos de serviço do Google SecOps.

É possível criar funções de transformação e operadores lógicos personalizados baseados em Python diretamente no ambiente de desenvolvimento integrado e usá-los nos manuais para casos de uso complexos e versáteis.

Pacotes de extensão

Um pacote de extensão é um tipo de integração especializada projetada para funcionar como um contêiner para funções de transformação personalizadas e operadores lógicos. Ao contrário das integrações padrão, os pacotes de extensão não exigem configuração de instância e podem ser criados diretamente no ambiente de desenvolvimento integrado.

Práticas recomendadas para pacotes de extensões

• Consolidação:crie um pacote de extensão principal e adicione várias funções de transformação ou operadores lógicos a ele.
• Separação:crie um novo pacote de extensão quando precisar de um conjunto diferente de bibliotecas Python (dependências) que possam entrar em conflito com o pacote principal.

Importante:para criar pacotes de extensão no IDE, é necessário ter a permissão Todos os ambientes.

Criar um pacote de extensões

Para criar um pacote de extensão, siga estas etapas:

1. Acesse Resposta > IDE.
2. Clique em add Criar novo item.
3. Selecione Pacote de extensão no menu suspenso.
4. Dê um Nome exclusivo ao pacote de extensão.
Observação:o nome não pode ser mudado após a criação.
5. Clique em Salvar.

Fazer upload de dependências

Assim como as integrações padrão, os pacotes de extensão são executados em um ambiente virtual em que é possível gerenciar bibliotecas Python.

Para gerenciar suas bibliotecas, siga estas etapas:

1. Abra as configurações do pacote de extensões no ambiente de desenvolvimento integrado.
2. Adicione as bibliotecas Python necessárias do PyPi ou faça upload delas do seu computador.

Essas dependências estão disponíveis para todos os transformadores e operadores lógicos contidos nesse pacote de extensão específico.

Importar e exportar

É possível importar e exportar manualmente pacotes de extensão diretamente na interface do IDE.

Observação:a importação e a exportação podem não estar disponíveis para clientes que ainda não concluíram a migração da etapa 2. Para mais informações, consulte a Visão geral da migração do SOAR.

Transformadores personalizados

Os transformadores personalizados são funções Python definidas pelo usuário que estendem as funções predefinidas no Criador de expressões. É possível criar essas funções diretamente no ambiente de desenvolvimento integrado para extrair e manipular dados, e elas podem ser usadas com as funções integradas atuais.

Criar um transformador personalizado

Para definir um novo transformador personalizado, siga estas etapas:

1. No IDE, localize o pacote de extensão de destino.
2. Selecione o pacote de extensão de destino para adicionar um novo item a ele.
3. Selecione Função de transformação personalizada.
4. Forneça um nome a ela.
Observação:o nome não pode ser mudado após a criação.
5. Opcional: adicione uma descrição. Ele aparece quando você passa o cursor sobre o transformador personalizado no criador de expressões.
6. Defina a lógica do script usando Python. Você pode usar o modelo padrão fornecido como ponto de partida.
   • O script precisa incluir uma função main, conforme mostrado no modelo predefinido.
   • O script precisa retornar um resultado ao criador de expressões usando a função end do SDK.
   • A entrada do transformador personalizado pode ser de diferentes tipos (por exemplo, string ou lista). Converta para o tipo esperado na função main.
   • Você pode usar apenas um subconjunto dos métodos do SDK no ambiente de desenvolvimento integrado para transformadores:
     • transformer.extract_param("ParamName"): para recuperar valores de entrada.
     • transformer.LOGGER: para gravar registros de depuração.
     • transformer.end(result): para retornar o valor transformado.
7. Crie parâmetros:
   • Cada função de transformação personalizada inclui um parâmetro Input padrão. Esse parâmetro representa os dados de entrada, que são o marcador de posição a que a função se aplica. Não é possível excluir esse parâmetro.
   • Além disso, é possível adicionar parâmetros opcionais para serem usados na função.
8. Documentação (opcional): defina a documentação no produto para o Criador de expressões:
   • Entrada esperada:descreva o tipo de dados que a função espera receber para esse transformador (por exemplo, "String" ou "Lista de strings").
   • Saída esperada:descreva o tipo de dados que a função espera retornar para esse transformador (por exemplo, "booleano").
   • Exemplo de uso:forneça um exemplo de como invocar a função (por exemplo, if_empty("new_value")).

É possível testar a lógica da função de transformação personalizada diretamente no IDE antes de usá-la em um playbook. Isso permite verificar se o script Python processa corretamente vários tipos de entrada e parâmetros e retorna os resultados esperados.

Tempo limite

• Tempo limite padrão:1 minuto.
• Tempo limite máximo:3 minutos.

Observação: como a plataforma aguarda a conclusão da função, é necessário minimizar o tempo de execução. Concentre-se em transformações diretas de dados e evite processamento pesado ou consultas a fontes externas.

Usar transformadores personalizados no criador de expressões

Depois de salvos, os transformadores personalizados aparecem na lista de funções do Criador de expressões ao lado das funções integradas. Elas são identificadas pelo formato: ExtensionPackName.TransformerName. Ao passar o cursor sobre a função, a documentação gerada com base nas descrições dos parâmetros é exibida.

Suporte para todos os marcadores de posição (JSON e não JSON)

O criador de expressões é compatível com todos os marcadores de posição expostos no Designer de playbooks, incluindo resultados não JSON.

Para marcadores de posição que não são JSON:

• É possível inserir manualmente dados de amostra no criador de expressões para testar a lógica em relação a vários tipos de entrada: string, lista (valores separados por vírgulas) e JSON.
• Testar com um tipo de entrada não garante que o marcador de posição vai retornar esse tipo específico durante a execução.
• A maioria dos marcadores de posição é resolvida como strings, exceto tipos específicos que são resolvidos como uma string ou lista com base na quantidade (por exemplo, entity.identifier). Para esses casos, é recomendável sempre tratar a entrada como uma lista.

Observação:os dados de amostra são temporários e não serão salvos depois que você fechar o Criador de expressões ou salvar a expressão. Você precisará inserir novamente os dados de amostra se abrir o criador de novo.

Tratamento de erros

Se uma função de transformação personalizada encontrar um erro durante a execução, a ação do playbook que usa esse transformador vai falhar. A mensagem de erro específica gerada pelo script Python é mostrada na tela na visualização de execução do playbook, permitindo que você resolva problemas na lógica diretamente.

Operadores lógicos personalizados

Com os operadores lógicos personalizados, você define sua própria lógica booleana para comparar valores.

Criar um operador lógico personalizado

Para definir um novo operador lógico, siga estas etapas:

1. No IDE, localize o Pacote de extensões de destino.
2. Selecione Operador lógico personalizado.
3. Forneça um nome a ela.
Observação:o nome não pode ser mudado após a criação.
4. Opcional: adicione uma descrição para o menu de operadores lógicos no Playbook Designer.
5. Defina a lógica do script usando Python. Use o modelo predefinido fornecido como ponto de partida.
   • O script precisa incluir uma função main.
   • O script precisa retornar um resultado booleano para a condição usando a função end do SDK.
   • Você só pode usar um subconjunto dos métodos do SDK na IDE para operadores lógicos:
   • logical_operator.extract_param("ParamName"): para recuperar valores de entrada.
   • logical_operator.LOGGER: para gravar registros de depuração.
   • logical_operator.end(result): o resultado é um valor booleano (true ou false).

Você pode testar sua lógica de operador lógico personalizada diretamente no ambiente de desenvolvimento integrado. Isso permite inserir valores de teste para os argumentos e verificar se a função retorna o resultado booleano correto (True ou False) com base nas condições definidas.

Parâmetros

Os operadores lógicos personalizados aceitam dois parâmetros: Lado esquerdo (obrigatório e não editável) e Lado direito (opcional e pode ser desativado pelo usuário).

• Exemplo 1:if [left side] not in [right side].
• Exemplo 2:if [left side] is greater than 80 (sem lado direito).

Tempo limite

• Tempo limite padrão:1 minuto.
• Tempo limite máximo:3 minutos.

Observação:como a plataforma aguarda a conclusão da função, é necessário minimizar o tempo de execução. A prática recomendada é se concentrar em transformações diretas de dados e evitar consultar fontes externas ou realizar processamentos pesados.

Usar em playbooks

Os operadores lógicos personalizados aparecem no menu de operadores em Condições do playbook, Condições da ação anterior e Seleção de entidade.

Os operadores lógicos personalizados podem ser selecionados junto com os operadores padrão (por exemplo, "Igual a" ou "Contém").

Tratamento de erros

Se uma função de operador lógico personalizada encontrar um erro durante a execução, a condição ou etapa do playbook que usa esse operador vai falhar. A mensagem de erro retornada pelo script Python é exibida na visualização de execução do playbook para ajudar na solução de problemas.

Limitações

• Funções de transformação personalizadas e operadores lógicos não são compatíveis com gatilhos ou webhooks.

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