Desenvolver transformadores personalizados
É possível criar funções de transformação personalizadas baseadas em Python e operadores lógicos diretamente no ambiente de desenvolvimento integrado e usá-los nos seus playbooks para casos de uso complexos e versáteis.
Pacotes de extensão
Um pacote de extensão é um tipo de integração especializado projetado para atuar 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ão
- 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.
Criar um pacote de extensões
Para criar um novo pacote de extensões, siga estas etapas:
- Acesse Automação > IDE. Se você estiver em uma plataforma somente SOAR, acesse Resposta > IDE.
- Clique em add Criar novo item.
- Selecione Pacote de extensão no menu suspenso.
- Dê um Nome exclusivo para o pacote de extensões.
- 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:
- Abra as configurações do pacote de extensões no ambiente de desenvolvimento integrado.
- Adicione as bibliotecas do 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.
Transformers personalizados
Os transformadores personalizados são funções Python definidas pelo usuário que ampliam as funções pré-criadas no Criador de Expressões. É possível criá-las 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:
- No ambiente de desenvolvimento integrado, localize o pacote de extensões de destino.
- Selecione o pacote de extensões de destino para adicionar um novo item.
- Selecione Função de transformação personalizada.
- Forneça um nome a ela.
- Opcional: adicione uma descrição. Isso é exibido quando você passa o cursor sobre o transformador personalizado no Criador de Expressões.
- Defina a lógica do script usando Python. Use 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 para o criador de expressões usando a função
enddo SDK. - A entrada do transformador personalizado pode ser de diferentes tipos
(por exemplo, string ou lista). Converta-o para o tipo esperado
na função
main. - É possível 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 para depuração.transformer.end(result): para retornar o valor transformado.
- O script precisa incluir uma função
- Crie parâmetros:
- Cada função de transformador personalizado 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 este parâmetro.
- Além disso, é possível adicionar parâmetros opcionais para serem usados na função.
- 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 ambiente de desenvolvimento integrado 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.
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. Eles são identificados 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 que não sã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 vários tipos de entrada: string, lista (valores separados por vírgulas) e JSON.
- O teste com um tipo de entrada não garante que o marcador de posição vai retornar esse tipo específico no momento da execução.
- A maioria dos marcadores de posição é resolvida como strings, exceto por tipos específicos que
são resolvidos como uma string ou lista com base na quantidade (por exemplo,
entity.identifier). Para esses, é recomendável sempre tratar a entrada como uma lista.
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 em Python é exibida na tela na visualização de execução do playbook, permitindo que você resolva o problema de lógica diretamente.
Operadores lógicos personalizados
Os operadores lógicos personalizados permitem que você defina 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:
- No ambiente de desenvolvimento integrado, localize o pacote de extensões de destino.
- Selecione Operador lógico personalizado.
- Forneça um nome a ela.
- Opcional: adicione uma descrição para o menu de operadores lógicos no Playbook Designer.
- 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
enddo SDK. - É possível usar apenas um subconjunto dos métodos do SDK no ambiente de desenvolvimento integrado para operadores lógicos:
logical_operator.extract_param("ParamName"): para recuperar valores de entrada.logical_operator.LOGGER: para gravar registros para depuração.logical_operator.end(result): o resultado é um valor booleano (trueoufalse).
- O script precisa incluir uma função
Você pode testar sua lógica de operador lógico personalizado diretamente no ambiente de desenvolvimento integrado. Isso permite que você insira valores de teste para os argumentos e verifique se a função retorna o resultado booleano correto (verdadeiro ou falso) 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; 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.
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 personalizado 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.