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

Suportado em:

Google secops SOAR

Nota: esta funcionalidade está abrangida pelos Termos das Ofertas de Pré-DG dos Termos Específicos do Serviço de Operações de Segurança da Google. As funcionalidades de pré-DG podem ter suporte limitado e as alterações às funcionalidades de pré-DG podem não ser compatíveis com outras versões de pré-DG. Para mais informações, consulte as diretrizes dos serviços de apoio técnico do Google SecOps e os Termos Específicos dos Serviços do Google SecOps.

Pode criar funções de transformação personalizadas baseadas em Python e operadores lógicos diretamente no IDE e usá-los nos seus manuais de soluções para exemplos de utilização complexos e versáteis.

Pacotes de extensões

Um pacote de extensões é um tipo de integração especializado concebido para funcionar como um contentor para funções de transformação personalizadas e operadores lógicos. Ao contrário das integrações padrão, os pacotes de extensões não requerem configuração de instâncias e podem ser criados diretamente a partir do IDE.

Práticas recomendadas para pacotes de extensões

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

Importante: a criação de pacotes de extensões no IDE requer a autorização Todos os ambientes.

Crie um pacote de extensões

Para criar um novo pacote de extensões, siga estes passos:

1. Aceda a Resposta > IDE.
2. Clique em adicionar Criar novo item.
3. Selecione Pacote de extensões no menu pendente.
4. Indique um nome exclusivo para o pacote de extensões.
Nota: não é possível alterar o nome após a criação.
5. Clique em Guardar.

Carregue dependências

Tal como as integrações padrão, os pacotes de extensões são executados num ambiente virtual onde pode gerir bibliotecas Python.

Para gerir as suas bibliotecas, siga estes passos:

1. Abra as definições do pacote de extensões no IDE.
2. Adicione as bibliotecas Python necessárias a partir do PyPi ou carregue-as a partir do seu computador.

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

Importar e exportar

Pode importar e exportar manualmente pacotes de extensões diretamente na interface do IDE.

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

Transformadores personalizados

Os transformadores personalizados são funções Python definidas pelo utilizador que expandem as funções pré-criadas no criador de expressões. Pode criá-las diretamente no IDE para extrair e manipular dados, e podem ser usadas juntamente com as funções incorporadas existentes.

Crie um transformador personalizado

Para definir um novo transformador personalizado, siga estes passos:

1. No IDE, localize o pacote de extensões de destino.
2. Selecione o pacote de extensões de destino para adicionar um novo item no pacote.
3. Selecione Função de transformação personalizada.
4. Atribua-lhe um nome.
Nota: não é possível alterar o nome após a criação.
5. Opcional: adicione uma descrição. Esta informação é apresentada quando passa o cursor do rato sobre o transformador personalizado no criador de expressões.
6. Defina a lógica do script com Python. Pode usar o modelo predefinido fornecido como ponto de partida.
   • O script tem de incluir uma função main, conforme mostrado no modelo predefinido.
   • O script tem de devolver um resultado ao criador de expressões através da função end do SDK.
   • A entrada do transformador personalizado pode ser de diferentes tipos (por exemplo, string ou lista). Certifique-se de que o converte no tipo esperado na sua função main.
   • Só pode usar um subconjunto dos métodos do SDK no IDE para transformadores:
     • transformer.extract_param("ParamName"): para obter valores de entrada.
     • transformer.LOGGER: para escrever registos para depuração.
     • transformer.end(result): para devolver o valor transformado.
7. Crie parâmetros:
   • Cada função de transformação personalizada inclui um parâmetro Input predefinido. Este parâmetro representa os dados de entrada, que é o marcador de posição ao qual a função se aplica. Não pode eliminar este parâmetro.
   • Além disso, pode adicionar parâmetros opcionais para utilização na sua 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 este transformador (por exemplo, "String" ou "Lista de strings").
   • Resultado esperado: descreva o tipo de dados que a função espera devolver para este transformador (por exemplo, "booleano").
   • Exemplo de utilização: forneça um exemplo de como invocar a função (por exemplo, if_empty("new_value")).

Pode testar a lógica da função de transformação personalizada diretamente no IDE antes de a usar num manual de estratégias. Isto permite-lhe verificar se o seu script Python processa corretamente vários tipos de entrada e parâmetros, e devolve os resultados esperados.

Tempo limite

• Predefinição de tempo limite: 1 minuto.
• Tempo limite máximo: 3 minutos.

Nota: uma vez que a plataforma aguarda a conclusão da função, tem de minimizar o tempo de execução. Concentre-se nas transformações de dados diretas e evite o processamento pesado ou a consulta de origens externas.

Use transformadores personalizados no criador de expressões

Depois de guardados, os transformadores personalizados aparecem na lista de funções do criador de expressões juntamente com as funções incorporadas. São identificados pelo formato: ExtensionPackName.TransformerName. Passar o cursor do rato sobre a função apresenta a documentação gerada a partir das descrições dos parâmetros.

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

O criador de expressões suporta todos os marcadores de posição expostos no criador de manuais de soluções, incluindo resultados não JSON.

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

• Pode introduzir manualmente dados de exemplo 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.
• Os testes com um tipo de entrada não garantem que o marcador de posição devolva esse tipo específico no tempo de execução.
• A maioria dos marcadores de posição é resolvida como strings, exceto tipos específicos que são resolvidos como uma string ou uma lista com base na respetiva quantidade (por exemplo, entity.identifier). Para estes, recomenda-se que trate sempre a entrada como uma lista.

Nota: os dados de exemplo são temporários e não são guardados depois de fechar o criador de expressões ou guardar a expressão. Tem de introduzir novamente os dados de exemplo se abrir novamente o criador.

Processamento 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 falha. A mensagem de erro específica gerada pelo script Python é apresentada no ecrã na vista de execução do manual de procedimentos, o que lhe permite resolver problemas da lógica diretamente.

Operadores lógicos personalizados

Os operadores lógicos personalizados permitem-lhe definir a sua própria lógica booleana para comparar valores.

Crie um operador lógico personalizado

Para definir um novo operador lógico, siga estes passos:

1. No IDE, localize o pacote de extensões de destino.
2. Selecione Operador lógico personalizado.
3. Atribua-lhe um nome.
Nota: não é possível alterar o nome 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 com Python. Pode usar o modelo predefinido fornecido como ponto de partida.
   • O script tem de incluir uma função main.
   • O script tem de devolver um resultado booleano à condição através da função end do SDK.
   • Só pode usar um subconjunto dos métodos do SDK no IDE para operadores lógicos:
   • logical_operator.extract_param("ParamName"): para obter valores de entrada.
   • logical_operator.LOGGER: para escrever registos para depuração.
   • logical_operator.end(result): o resultado é um valor booleano (true ou false).

Pode testar a lógica do operador lógico personalizado diretamente no IDE. Isto permite-lhe introduzir valores de teste para os argumentos e verificar se a função devolve o resultado booleano (verdadeiro ou falso) correto 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 utilizador).

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

Tempo limite

• Predefinição de tempo limite: 1 minuto.
• Tempo limite máximo: 3 minutos.

Nota: uma vez que a plataforma aguarda a conclusão da função, tem de minimizar o tempo de execução. A prática recomendada é focar-se nas transformações diretas de dados e evitar consultar origens externas ou realizar processamento pesado.

Use em guias interativos

Os operadores lógicos personalizados aparecem no menu de operadores em Condições do Playbook, Condições de ações anteriores e Seleção de entidades.

Os operadores lógicos personalizados são selecionáveis juntamente com os operadores padrão (por exemplo, "Igual a" ou "Contém").

Processamento de erros

Se uma função de operador lógico personalizado encontrar um erro durante a execução, a condição ou o passo do manual de procedimentos que usa esse operador falha. A mensagem de erro devolvida pelo script Python é apresentada na vista de execução do manual de procedimentos para ajudar na resolução de problemas.

Limitações

• As funções de transformação personalizadas e os operadores lógicos não são suportados em acionadores nem em webhooks.

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