Esta página se ha traducido con Cloud Translation API.

Crear acciones personalizadas

Disponible en:

SecOps de Google SOAR

En tu primera integración personalizada, definiste sus parámetros y creaste una acción Ping para probar la conexión. En este documento se explica cómo crear dos acciones nuevas para tu integración personalizada:

Obtener detalles del dominio: obtiene información sobre el dominio y muestra el resultado en formato JSON.
Enriquecer entidades: enriquece las entidades con detalles del dominio.

Crear una acción personalizada

Para crear una acción personalizada, sigue estos pasos:

Ve al entorno de desarrollo integrado (IDE) y haz clic en Añadir para añadir un nuevo elemento de IDE.
Selecciona el botón de radio Acción.
Asigna el nombre Get Domain Details a la acción y selecciona la integración.
Haz clic en Crear. El IDE genera una plantilla con comentarios y explicaciones de código integrados.

Configurar parámetros de acción

Según la documentación de la API XML de WHOIS, la acción Get Domain Details (Obtener detalles del dominio) requiere dos parámetros: Check Availability y Domain Name. Para configurar estos parámetros, sigue estos pasos:

En el módulo IDE, haga clic en Añadir.
Crea el primer parámetro: rellena los campos de Comprobar disponibilidad y haz clic en Guardar. Este parámetro indica si el dominio está disponible o no. El resultado se usará en la automatización que crees más adelante.
Crea el segundo parámetro: rellena los campos de Nombre de dominio y haz clic en Guardar. Usa este campo para introducir el dominio que quieres que compruebe la acción.

Editar la acción Obtener detalles del dominio

Para editar la acción Obtener detalles del dominio, sigue estos pasos:

Copia el código proporcionado para Get Domain Details (Obtener detalles del dominio) y pégalo en el IDE. Revisa el código. El objeto debe usar el método end de la clase para devolver un mensaje de salida y un valor de resultado. Por ejemplo:
siemplify.end(msg, None)

Extraer parámetros de integración y acción: los parámetros de integración, como la clave de API, se extraen mediante la función siemplify.extract_configuration_param. Del mismo modo, los parámetros de acción que hayas configurado, incluidos Domain Name y Check availability, se extraen con la función 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)

Crea la solicitud y procesa el resultado:

Una vez que hayas extraído los parámetros de integración y de acción, podrás crear la URL de solicitud. La URL se crea en función del valor booleano del parámetro availability_check.
Cuando la URL esté lista, envía una solicitud al sitio de WHOIS.
Analiza la respuesta del sitio y añade los datos pertinentes al resultado de la acción.

Define el mensaje de salida que se mostrará al usuario e incluye el 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()

Añadir un resultado en JSON a la acción

Como parte de la acción Get Domain Details (Obtener detalles del dominio), haga clic en Get Domain Details (Obtener detalles del dominio) para añadir un ejemplo de JSON. Usa el ejemplo de JSON del diseñador de guiones en el procedimiento Crea tu primera automatización para extraer un campo específico del JSON.

Obtén el JSON: copia el JSON del ejemplo de JSON del sitio de WHOIS.
Habilita el icono JSON: en la pestaña Detalles del IDE, activa el interruptor Incluir resultado de JSON para que el icono JSON se muestre en la parte superior del IDE.
Importa el JSON: haz clic en file_json Gestionar ejemplo de JSON > login Importar ejemplo de JSON.

Probar la acción

Para probar la acción que has creado, sigue estos pasos:

Vaya a la pestaña Pruebas.
En Ámbito, selecciona tu Caso de prueba y tu Instancia de integración.
En el IDE, haz clic en presentación Reproducir.
Consulta el resultado de la acción en la pestaña Pruebas. También puede revisar los registros e impresiones en la pestaña Salida de depuración una vez que se haya completado la prueba.

Crear un caso de prueba

Si no tienes ningún caso de prueba en tu entorno, ve a Casos > Ingestar alerta como caso de prueba para crear uno. Esta acción crea un caso de prueba que aparece con la etiqueta Prueba en tu cola de casos. Después de crear el caso de prueba, vuelve al IDE y elige el caso de prueba de la lista.

Para crear un caso de prueba, sigue estos pasos:

Ve a la página Casos y selecciona uno.
Ingiere la alerta como caso de prueba. Se creará un nuevo caso con la etiqueta Prueba en tu cola de casos.

Una vez que hayas creado un caso de prueba, vuelve al IDE y selecciónalo en la lista.

Crear una acción de enriquecimiento

En esta parte del procedimiento, nos centraremos en crear una acción de enriquecimiento para añadir datos nuevos a las entidades. Los datos enriquecidos se pueden consultar en el Explorador de entidades. Para crear una acción de enriquecimiento, sigue estos pasos:

En el IDE, crea una acción y asígnale el nombre Enrich Entities.

Copia y pega el siguiente código en la acción:


  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()

Extrae los parámetros. La secuencia de comandos extrae la clave de API de la configuración de la integración. Esta clave es necesaria para autenticar las solicitudes a la API XML de WHOIS.
Identifica las entidades objetivo. La secuencia de comandos identifica las entidades que se deben procesar. Recorre todas las entidades y se centra solo en dos tipos:

Nombres de host no 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

Analiza el dominio y define el paso de enriquecimiento de la acción y el mensaje de salida. Esta acción se ejecuta en un ámbito Entity y, por lo tanto, no requiere que configure parámetros específicos, ya que están insertados en el 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)

Habilita la acción y haz clic en Guardar. Ahora ha creado una integración personalizada con tres acciones personalizadas:

Una acción Ping para probar la conexión con el producto de la API XML de WHOIS.
Una acción Get Domain Details (Obtener detalles del dominio) para extraer datos sobre un dominio y presentarlos como un resultado JSON.
Una acción Enriquecer entidades para añadir datos adicionales a las entidades objetivo, que puedes ver en el módulo Explorador de entidades.

Ahora ya puedes crear tu primera automatización con las acciones que has personalizado.

¿Necesitas más ayuda? Recibe respuestas de los miembros de la comunidad y de los profesionales de Google SecOps.