Esta página foi traduzida pela API Cloud Translation.

Crie ações personalizadas

Compatível com:

Google secops SOAR

Na sua primeira integração personalizada, definiu os respetivos parâmetros e criou uma ação Ping para testar a ligação. Este documento explica como criar duas novas ações para a sua integração personalizada:

Get domain details: obtém informações do domínio e apresenta o resultado no formato JSON.
Enrich entities: enriquece as entidades com detalhes do domínio.

Crie uma ação personalizada

Para criar uma ação personalizada, siga estes passos:

Aceda ao ambiente de programação integrado (IDE) e clique em Adicionar para adicionar um novo item do IDE.
Selecione o botão de opção Ação.
Atribua um nome à ação Get Domain Details e selecione a integração.
Clique em Criar. O IDE gera um novo modelo com explicações e comentários de código incorporados.

Configure parâmetros de ações

Com base na documentação da API XML WHOIS, a ação Get Domain Details requer dois parâmetros: Check Availability e Domain Name. Para configurar estes parâmetros, siga estes passos:

No módulo IDE, clique em Adicionar.
Crie o primeiro parâmetro: preencha os campos para Verificar disponibilidade e clique em Guardar. Este parâmetro indica se o domínio está disponível ou não, e o respetivo resultado é usado na automatização que criar mais tarde.
Crie o segundo parâmetro: preencha os campos para Nome do domínio e clique em Guardar. Use este campo para introduzir o domínio que quer que a ação verifique.

Edite a ação Obter detalhes do domínio

Para editar a ação Obter detalhes do domínio, siga estes passos:

Copie o código fornecido para Get Domain Details e cole-o no IDE. Reveja o código. O objeto tem de usar o método end da classe para devolver uma mensagem de saída e um valor de resultado, por exemplo:
siemplify.end(msg, None)

Extraia parâmetros de integração e ação: os parâmetros de integração, como a chave da API, são extraídos através da função siemplify.extract_configuration_param. Da mesma forma, os parâmetros de ação que configurou, 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 o pedido e processe o resultado:

Depois de extrair os parâmetros de integração e de ação, pode criar o URL do pedido. O URL é construído com base no valor Booleano do parâmetro availability_check.
Quando o URL estiver pronto, envie um pedido para o site WHOIS.
Analise a resposta do site e adicione os dados relevantes ao resultado da ação.

Defina a mensagem de saída que vai ser apresentada ao utilizador 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()

Adicione um resultado JSON à ação

Como parte da ação Get Domain Details, clique em Get Domain Details para adicionar um exemplo JSON. Use o exemplo de JSON no criador de manuais de procedimentos na procedimento "Crie a sua primeira automatização" para extrair um campo específico no JSON.

Obtenha o JSON: copie o JSON do exemplo de JSON do site WHOIS.
Ative o ícone JSON: no separador Detalhes do IDE, ative o botão Incluir resultado JSON para tornar o ícone JSON visível na parte superior do IDE.
Importe o JSON: clique em file_json Gerir exemplo de JSON > Iniciar sessão Importar exemplo de JSON.

Teste a ação

Para testar a ação que criou, siga estes passos:

Aceda ao separador Testes.
No Âmbito, selecione o Exemplo de teste e a Instância de integração.
Clique em apresentação de diapositivos Reproduzir no IDE.
Veja o resultado da ação no separador Testes. Também pode rever os registos e as impressões consultando o separador Resultado da depuração após a conclusão do teste.

Crie um exemplo de teste

Se não tiver casos de teste no seu ambiente, aceda a Casos > Carregar alerta como caso de teste para criar um. Esta ação cria um registo de teste que aparece com a etiqueta Teste na fila de registos. Depois de criar o exemplo de teste, volte ao IDE e escolha o exemplo de teste na lista.

Para criar um exemplo de teste, siga estes passos:

Aceda à página Registos e selecione um registo.
Carregue o alerta como um caso de teste. Esta ação cria um novo registo com a etiqueta Teste na fila de registos.

Depois de criar um exemplo de teste, regresse ao IDE e selecione-o na lista.

Crie uma ação de enriquecimento

Esta parte do procedimento centra-se na criação de uma ação de enriquecimento para adicionar novos dados a entidades. Em seguida, pode ver os dados enriquecidos no explorador de entidades. Para criar uma ação de enriquecimento, siga estes passos:

No IDE, crie uma nova ação e atribua-lhe o nome 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()

Extrair parâmetros. O script extrai a chave da API da configuração da integração. Esta chave é necessária para autenticar pedidos à API XML WHOIS.
Identifique entidades de destino. O script identifica as entidades a processar. Itera todas as entidades e foca-se apenas em dois tipos:

Nomes de anfitrião 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 o passo de enriquecimento da ação e da mensagem de saída. Esta ação é executada num âmbito de Entity e, por isso, não requer a configuração de parâmetros específicos. Estes já estão incorporados no 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 Guardar. Criou uma integração personalizada com três ações personalizadas:

Uma ação Ping para testar a ligação ao produto da API XML 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 dados adicionais a entidades de destino, que pode ver no módulo Explorador de entidades.

Agora, já pode criar a sua primeira automatização com as ações que personalizou.

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