Desenvolver sua primeira ação personalizada

Compatível com:

Google SecOps SOAR

Na sua primeira integração personalizada, você definiu os parâmetros e criou uma ação Ping para testar a conexão. Este documento orienta você sobre como criar duas novas ações para sua integração personalizada:

• Receber detalhes do domínio: recupera informações do domínio e apresenta o resultado no formato JSON.
• Aprimorar entidades: aprimora entidades com detalhes do domínio.

Observação:esses procedimentos exigem conhecimento de Python e programação orientada a objetos. Também recomendamos explorar os módulos do SDK.

Criar uma ação personalizada

Para criar uma ação personalizada, siga estas etapas:

1. Acesse o ambiente de desenvolvimento integrado (IDE, na sigla em inglês) e clique em Adicionar para incluir um novo item do IDE.
2. Selecione o botão de opção Ação.
3. Nomeie a ação Get Domain Details e selecione a integração.
4. Clique em Criar. O IDE gera um novo modelo com comentários e explicações de código integrados.

Configurar parâmetros de ação

Com base na documentação da API XML do WHOIS, a ação Receber detalhes do domínio exige dois parâmetros: Check Availability e Domain Name. Para configurar esses parâmetros, siga estas etapas:

1. No módulo do IDE, clique em Adicionar.
2. Crie o primeiro parâmetro: preencha os campos de Verificar disponibilidade e clique em Salvar. Esse parâmetro indica se o domínio está disponível ou não, e o resultado será usado na automação que você criar mais tarde.
3. Crie o segundo parâmetro: preencha os campos de Nome do domínio e clique em Salvar. Use esse campo para inserir o domínio que você quer que a ação verifique.

Editar a ação "Receber detalhes do domínio"

Para editar a ação Receber detalhes do domínio, siga estas etapas:

1. Copie o código fornecido para Receber detalhes do domínio e cole-o no IDE. Revise o código. O objeto precisa usar o método end da classe para retornar uma mensagem de saída e um valor de resultado, por exemplo:
   siemplify.end(msg, None)
2. Extrair parâmetros de integração e ação: os parâmetros de integração, como a chave de API, são extraídos usando a siemplify.extract_configuration_param função. Da mesma forma, os parâmetros de ação configurados, incluindo Domain Name e Check availability, são extraídos com a função siemplify.extract_action_param.

   
       api_key =
       siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
       param_name="API Key") 
   url = f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json" 
       domain = siemplify.extract_action_param(param_name="Domain Name",
       print_value=True) availability_check =
       siemplify.extract_action_param(param_name="Check availability",
       is_mandatory=False, print_value=True)
     

3. Crie a solicitação e processe o resultado:
1. Depois de extrair os parâmetros de integração e ação, você pode criar o URL da solicitação. O URL é criado com base no valor booleano do parâmetro availability_check.
2. Quando o URL estiver pronto, envie uma solicitação ao site do WHOIS.
3. Analise a resposta do site e adicione os dados relevantes ao resultado da ação.
4. Defina a mensagem de saída que será apresentada ao usuário e inclua o resultado JSON.
   

   
     # Add domain to scan
         url = f"{url}&domainName={domain}"
         # Determine availability check
         if availability_check.lower() == 'true':
             availability_check_qs = 1
         else:
             availability_check_qs = 0
         url = f"{url}&da={availability_check_qs}"
         response = requests.get(url)
         response.raise_for_status()
         # Add a Json result that can be used in the next steps of the playbook.
         siemplify.result.add_result_json(response.json())
         # Add the Json to the action result presented in the context details.
         siemplify.result.add_json("WhoisDetails", response.json())
         msg = f"Fetched data for {domain}"
         siemplify.end(msg, None)
     if __name__ == "__main__":
         main()
     

Adicionar um resultado JSON à ação

Como parte da ação Receber detalhes do domínio, clique em Receber detalhes do domínio para adicionar um exemplo de JSON. Use o exemplo de JSON no designer de playbook no "Criar sua primeira automação" procedimento para extrair um campo específico no JSON.

1. Receber o JSON: copie o JSON do exemplo de JSON do site do WHOIS.
2. Ativar o ícone JSON: na guia Detalhes do IDE, ative a opção Incluir resultado JSON para que o ícone JSON fique visível na parte de cima do IDE.
3. Importar o JSON: clique em file_json Gerenciar exemplo de JSON > login Importar exemplo de JSON.

Testar a ação

Para testar a ação criada, siga estas etapas:

1. Acesse a guia Teste.
2. Em Escopo , selecione seu Caso de teste e Instância de integração.
3. Clique em slideshow Reproduzir no IDE.
4. Confira o resultado da ação na guia Teste. Você também pode revisar os registros e impressões marcando a guia Saída de depuração após a conclusão do teste.

Criar um caso de teste

Se você não tiver casos de teste no seu ambiente, acesse Casos > Ingerir alerta como caso de teste para criar um. Essa ação cria um caso de teste que aparece com um rótulo Teste na sua fila de casos. Depois de criar o caso de teste, volte ao IDE e escolha o caso de teste na lista.

Para criar um caso de teste, siga estas etapas:

1. Acesse a página Casos e selecione um caso.
2. Ingira o alerta como um caso de teste. Isso cria um novo caso com um rótulo Teste na fila de casos.

Depois de criar um caso de teste, volte ao IDE e selecione-o na lista.

Criar uma ação de aprimoramento

Esta parte do procedimento se concentra na criação de uma ação de aprimoramento para adicionar novos dados às entidades. Os dados aprimorados podem ser visualizados no Explorador de entidades. Para criar uma ação de aprimoramento, siga estas etapas:

1. No IDE, crie uma nova ação e nomeie-a como Enrich Entities.
2. Copie e cole o código a seguir na ação:

   
     from SiemplifyAction import SiemplifyAction 
     from SiemplifyUtils import output_handler 
     from SiemplifyDataModel import EntityTypes
     
     import requests
     
     # Example Consts: 
     INTEGRATION_NAME = "My first Integration - Whois XML API" 
   
     SCRIPT_NAME = "WHOIS XML API EnrichEntities"
     
     @output_handler 
     def main():    
         siemplify = SiemplifyAction()    
         siemplify.script_name = SCRIPT_NAME    
         siemplify.LOGGER.info("================= Main - Param Init =================")     
   
         api_key =
         siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
         param_name="API Key") url =
         f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json"
         
         
         siemplify.LOGGER.info("----------------- Main - Started -----------------")
         output_message = "output message :" # human readable message, showed in UI
         as the action result successful_entities = [] # In case this actions
         contains entity based logic, collect successful entity.identifiers 
         
       for entity in siemplify.target_entities:        
       siemplify.LOGGER.info(f"processing entity {entity.identifier}")
         if (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal)
         or entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier
         
               scan_url = f"{url}&domainName={entity_to_scan}"              response = requests.get(scan_url)            
               response.raise_for_status()            
               register_details = response.json().get("WhoisRecord", {}).get("registrant", {})            if register_details:                
           entity.additional_properties.update(register_details)        successful_entities.append(entity) 
   
         if successful_entities:        
           output_message += "\n Successfully processed entities:\n {}".format("\n
           ".join([x.identifier for x in successful_entities]))
           siemplify.update_entities(successful_entities) # This is the actual
           enrichment (this function sends the data back to the server) 
       else:        
           output_message += "\n No entities where processed."      
     result_value = len(successful_entities) 
   
         siemplify.LOGGER.info("----------------- Main - Finished -----------------")    
         siemplify.end(output_message, result_value) 
   
     if __name__ == "__main__":    
         main()
     

3. Extraia os parâmetros. O script extrai a chave de API da configuração da integração. Essa chave é necessária para autenticar solicitações à API XML do WHOIS.
4. Identifique as entidades de destino. O script identifica quais entidades processar. Ele itera por todas as entidades e se concentra apenas em dois tipos:
• Nomes de host não internos
• URLs

  for entity in siemplify.target_entities:        
        siemplify.LOGGER.info(f"processing entity {entity.identifier}") if
        (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal) or
        entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier
  

5. Analise o domínio e defina a etapa de aprimoramento da ação e a mensagem de saída. Essa ação é executada em um escopo de entidade e, portanto, não exige que você configure parâmetros específicos. Isso já está incorporado ao código:

   
     scan_url = f"{url}&domainName={entity_to_scan}"
   
                 response = requests.get(scan_url) response.raise_for_status()
                 register_details = response.json().get("WhoisRecord",
                 {}).get("registrant", {}) if register_details:
                     entity.additional_properties.update(register_details)
                     successful_entities.append(entity)
   
   
         if successful_entities:
             output_message += "\n Successfully processed entities:\n {}".format("\n
             ".join([x.identifier for x in successful_entities]))
             siemplify.update_entities(successful_entities) # This is the actual
             enrichment (this function sends the data back to the server)
         else:
             output_message += "\n No entities where processed."
   
   
         result_value = len(successful_entities) 
     

6. Ative a ação e clique em Salvar. Agora você criou uma integração personalizada com três ações personalizadas:
• Uma ação Ping para testar a conexão com o produto da API XML do WHOIS.
• Uma ação Receber detalhes do domínio para extrair dados sobre um domínio e apresentá-los como um resultado JSON.
• Uma ação Aprimorar entidades para adicionar dados extras às entidades de destino, que podem ser visualizados no módulo Explorador de entidades.

Agora você está pronto para criar sua primeira automação usando as ações personalizadas.

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