Se usó la API de Cloud Translation para traducir esta página.

Crea acciones personalizadas

Compatible con:

Google SecOps 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: Recupera la información del dominio y presenta el resultado en formato JSON.
Enrich entities: Enriquece las entidades con detalles del dominio.

Crea una acción personalizada

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

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

Configura parámetros de acción

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

En el módulo del IDE, haz clic en Agregar.
Crea el primer parámetro: Completa los campos de Verificar disponibilidad y haz clic en Guardar. Este parámetro indica si el dominio está disponible o no, y su resultado se usará en la automatización que crearás más adelante.
Crea el segundo parámetro: Completa los campos de Nombre de dominio y haz clic en Guardar. Usa este campo para ingresar el dominio que quieres que verifique la acción.

Edita la acción Get Domain Details

Para editar la acción Get Domain Details, sigue estos pasos:

Copia el código proporcionado para Get Domain Details 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)

Extrae parámetros de integración y acción: Los parámetros de integración, como la clave de API, se extraen con la función siemplify.extract_configuration_param. Del mismo modo, los parámetros de acción que configuraste, 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)

Compila la solicitud y procesa el resultado:

Después de extraer los parámetros de integración y acción, puedes compilar la URL de solicitud. La URL se construye en función del valor booleano del parámetro availability_check.
Una vez que la URL esté lista, envía una solicitud al sitio de WHOIS.
Analiza la respuesta del sitio y agrega los datos pertinentes al resultado de la acción.

Define el mensaje de salida que se presentará al usuario y, luego, incluye el resultado en formato 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()

Agrega un resultado JSON a la acción

Como parte de la acción Get Domain Details, haz clic en Get Domain Details para agregar un ejemplo de JSON. Usa el ejemplo de JSON en el diseñador de la guía para extraer un campo específico en el JSON del procedimiento "Crea tu primera automatización".

Obtén el JSON: Copia el JSON del ejemplo de JSON del sitio de WHOIS.
Habilita el ícono de JSON: En la pestaña Details del IDE, habilita el botón de activación Include JSON Result para que el ícono de JSON sea visible en la parte superior del IDE.
Importa el archivo JSON: Haz clic en file_json Administrar plantilla JSON > login Importar ejemplo de JSON.

Prueba la acción

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

Ve a la pestaña Pruebas.
En Alcance, selecciona tu Caso de prueba y tu Instancia de integración.
Haz clic en presentación de diapositivas Reproducir en el IDE.
Consulta el resultado de la acción en la pestaña Testing. También puedes revisar los registros y las impresiones en la pestaña Debug Output después de que se complete la prueba.

Crea un caso de prueba

Si no tienes ningún caso de prueba en tu entorno, ve a Cases > Ingest alert as test case para crear uno. Esta acción crea un caso de prueba que aparece con la etiqueta Prueba en la 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.
Transfiere la alerta como caso de prueba. Esto creará un caso nuevo con la etiqueta Prueba en la cola de casos.

Después de crear un caso de prueba, vuelve al IDE y selecciónalo en la lista.

Crea una acción de enriquecimiento

Esta parte del procedimiento se enfoca en crear una acción de enriquecimiento para agregar datos nuevos a las entidades. Luego, los datos enriquecidos se pueden ver en el Explorador de entidades. Para crear una acción de enriquecimiento, sigue estos pasos:

En el IDE, crea una acción nueva 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 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 de XML de WHOIS.
Identifica las entidades objetivo. La secuencia de comandos identifica qué entidades se deben procesar. Itera por todas las entidades y se enfoca solo en dos tipos:

Nombres de host no internos
URL


  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 alcance de entidad y, por lo tanto, no requiere que configures parámetros específicos, ya que estos ya están incorporados 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 creaste una integración personalizada con tres acciones personalizadas:

Una acción de Ping para probar la conexión al producto de la API de WHOIS en XML.
Una acción Get Domain Details para extraer datos sobre un dominio y presentarlos como un resultado en JSON.
Una acción de Enrich Entities para agregar datos adicionales a las entidades objetivo, que puedes ver en el módulo Entity Explorer

Ahora puedes crear tu primera automatización con las acciones que personalizaste.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.