Esta página foi traduzida pela API Cloud Translation.

Criar ações personalizadas

Compatível com:

SecOps do Google 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 mostra 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.

Criar uma ação personalizada

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

Acesse o ambiente de desenvolvimento integrado (IDE) e clique em Adicionar para adicionar um novo item de IDE.
Selecione o botão de opção Ação.
Nomeie a ação Get Domain Details e selecione a integração.
Clique em Criar. O ambiente de desenvolvimento integrado 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 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:

No módulo do ambiente de desenvolvimento integrado, clique em Adicionar.
Crie o primeiro parâmetro: preencha os campos em 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.
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 "Extrair detalhes do domínio"

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

Copie o código fornecido para Get Domain Details e cole 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)

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 função siemplify.extract_configuration_param. 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)

Crie a solicitação e processe o resultado:

Depois de extrair os parâmetros de integração e ação, você pode criar o URL de solicitação. O URL é criado com base no valor booleano do parâmetro availability_check.
Quando o URL estiver pronto, envie uma solicitação ao site WHOIS.
Analise a resposta do site e adicione os dados relevantes ao resultado da ação.

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 em JSON. Use o exemplo JSON no designer de playbook no procedimento "Criar sua primeira automação" para extrair um campo específico no JSON.

Copie o JSON: copie o JSON do exemplo de JSON do site WHOIS.
Ative o ícone JSON: na guia Detalhes da IDE, ative a opção Incluir resultado JSON para que o ícone JSON fique visível na parte de cima da IDE.
Importe 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:

Acesse a guia Testes.
Em Escopo, selecione seu Caso de teste e Instância de integração.
Clique em apresentação de slides Reproduzir no ambiente de desenvolvimento integrado.
Confira o resultado da ação na guia Teste. Você também pode revisar os registros e impressões na 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 > Inserir alerta como caso de teste para criar um. Essa ação cria um caso de teste que aparece com o rótulo Teste na fila de casos. Depois de criar o caso de teste, volte ao ambiente de desenvolvimento integrado e escolha o caso de teste na lista.

Para criar um caso de teste, siga estas etapas:

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

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

Criar uma ação de enriquecimento

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

No ambiente de desenvolvimento integrado, crie uma ação e nomeie-a como Enrich Entities.

Copie e cole o seguinte código 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()

Extraia parâmetros. O script extrai a chave de API da configuração da integração. Essa chave é necessária para autenticar solicitações à API WHOIS XML.
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

Analise o domínio e defina a etapa de enriquecimento da ação e da 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)

Ative a ação e clique em Salvar. Agora você criou uma integração personalizada com três ações personalizadas:

Uma ação de ping para testar a conexão com o produto da API XML do WHOIS.
Uma ação Get Domain Details para extrair dados sobre um domínio e apresentá-los como um resultado JSON.
Uma ação Enriquecer entidades para adicionar mais dados às entidades de destino, que podem ser vistos no módulo Explorador de entidades.

Agora você já pode 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.