Reorganizamos nuestra estructura de navegación para que se alinee directamente con tus flujos de trabajo operativos. Consulta las notas de la versión de Google SecOps para obtener más información.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Desarrolla tu primera acción personalizada

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:

Get domain details: Recupera la información del dominio y presenta el resultado en formato JSON.
Enrich entities: Enriquece las entidades con los 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.
Nombra 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 los parámetros de la acción

Según la documentación de la API de WHOIS 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 Check Availability 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 crees más adelante.
Crea el segundo parámetro: Completa los campos de Domain Name y haz clic en Guardar. Usa este campo para ingresar el dominio que deseas 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 mostrar un mensaje de salida y un valor de resultado, por ejemplo:
siemplify.end(msg, None)

Extrae los parámetros de integración y acción: Los parámetros de integración, como la clave de API, se extraen con la siemplify.extract_configuration_param función. 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 la solicitud. La URL se crea según el 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 mostrará al usuario y agrega el resultado de 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 de 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 playbook en el "Crea tu primera automatización" procedimiento para extraer un campo específico en el JSON.

Obtén el JSON: Copia el JSON del ejemplo de JSON del sitio de WHOIS.
Habilita el ícono de JSON: En la pestaña Detalles del IDE, habilita el botón de activación Incluir resultado de JSON para que el ícono de JSON sea visible en la parte superior del IDE.
Importa el JSON: Haz clic en file_json Administrar muestra de 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 la Instancia de integración.
Haz clic en slideshow Reproducir en el IDE.
Consulta el resultado de la acción en la pestaña Pruebas. También puedes revisar los registros y las impresiones. Para ello, consulta la pestaña Resultado de depuración 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 Casos > Transferir alerta como caso de prueba para crear uno. Esta acción crea un caso de prueba que aparece con una 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 un caso.
Transfiere la alerta como caso de prueba. Se creará un caso nuevo con una etiqueta Prueba en tu cola de casos.

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

Crea una acción de enriquecimiento

Esta parte del procedimiento se centra en la creación de 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 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 de WHOIS XML.
Identifica las entidades de destino. La secuencia de comandos identifica qué entidades procesar. Itera a través de todas las entidades y se enfoca 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 alcance de entidad y, por lo tanto, no requiere que configures parámetros específicos. Esto ya está integrado 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 Ping para probar la conexión al producto de la API de XML de WHOIS.
Una acción Get Domain Details para extraer datos sobre un dominio y presentarlos como un resultado de JSON.
Una acción Enrich Entities para agregar datos adicionales a las entidades de destino, que puedes ver en el módulo Explorador de entidades.

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.