Crear una integración personalizada

Disponible en:

SecOps de Google SOAR

En este documento se explica cómo crear integraciones personalizadas en el entorno de desarrollo integrado (IDE) con la misma estructura que las integraciones comerciales. Puede encontrar y configurar integraciones personalizadas en Google Security Operations Marketplace para varios entornos. Después, puedes usarlas en guías, acciones manuales y agentes remotos. También se admite la importación y la exportación, al igual que con otros elementos del IDE.

Crear una integración personalizada en el IDE

Puedes crear una integración personalizada para el producto Armis y crear un gestor junto con una acción Ping. Para llevar a cabo este procedimiento, se presupone que tienes conocimientos de Python y de programación orientada a objetos.

Caso práctico: crear una integración personalizada de Armis

Para crear la integración personalizada en el IDE, sigue estos pasos:

1. En el menú principal, ve a Respuesta > IDE.
2. Haga clic en Crear nuevo elemento y seleccione Integración.
3. Escribe un nombre y haz clic en Crear.

La integración ahora aparece en la opción configuración Configuración, lo que indica que es una integración personalizada.

Haz clic en Configuración Configuración para ver los ajustes de la integración, donde puedes definir el icono, la descripción, las dependencias de Python y los parámetros de la integración.

Nota: Las dependencias de la secuencia de comandos son bibliotecas de Python que la integración personalizada necesita importar. Las dependencias se pueden añadir como archivos `.WHL`, `.TAR`, `.GZ` o `.PY`. Cada integración se ejecuta en su propio entorno virtual, lo que te permite usar diferentes versiones de la biblioteca aunque ya haya una instalada en el sistema. Por ejemplo, para usar otra versión de la biblioteca de solicitudes, descárgala de una fuente de confianza, como PyPI o GitHub, y añádela como dependencia de script. Si no está instalada en el entorno virtual, la integración recurre a la versión del sistema.

Crear un gestor personalizado

Los gestores son envoltorios de APIs de herramientas de terceros. Aunque no es obligatorio, te recomendamos que los uses en las integraciones que interactúan con herramientas externas. Los gestores no deben importar desde el SDK. Una vez creados, impórtalos en conectores, acciones y tareas.

Para crear un administrador personalizado, sigue estos pasos:

1. En el IDE, haz clic en Crear nuevo elemento y selecciona Gestor.
2. Selecciona la integración Armis e introduce el nombre de un gestor.
   
3. Edita y ejecuta la siguiente secuencia de comandos:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token - api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Respuesta) La respuesta que se va a validar
       :param error_msg: (str) El mensaje de error que se va a mostrar
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Nota: No es necesario que haya un gestor para realizar acciones básicas. Sin embargo, te recomendamos que crees uno cuando agrupes acciones pequeñas para analizar y transformar datos.

Parámetros, configuración de Google SecOps Marketplace y la acción Ping

Los parámetros definidos en los ajustes de integración aparecen en la configuración de Google SecOps Marketplace. Entre los parámetros se incluyen los siguientes:

• Raíz de la API: la URL base del servicio al que te vas a conectar.
• Secreto de API: una clave confidencial que se usa para autenticar tu aplicación con el servicio.
• Casilla Verificar SSL: si está habilitada, verifica que el certificado SSL de la conexión al servidor de Armis sea válido.
• Casilla Ejecutar de forma remota: opción que determina si el código o la tarea se ejecutarán en un servidor remoto en lugar de localmente. Cuando esta opción está habilitada, el sistema envía las instrucciones y los datos necesarios a un servidor específico para que se procesen.

Para actualizar los parámetros, sigue estos pasos:

1. Escribe las credenciales correctas.
2. Haz clic en Guardar > Probar.

Nota: Siempre debes hacer clic en Guardar después de actualizar las credenciales. Todas las integraciones de terceros deben implementar una acción Ping. El botón Probar ejecuta esta acción para validar la conectividad.

Si falta la acción Ping, el botón Prueba falla y muestra una X roja.

Implementar una acción Ping

La lógica de la acción Ping funciona como una autenticación correcta.

Para implementar una acción Ping, siga estos pasos:

1. En el IDE, crea una acción en la integración de Armis llamada Ping.
2. Usa el método ArmisManager auth para verificar la autenticación.

Habilitar la integración

Para habilitar la integración, sigue estos pasos:

1. En Respuesta > IDE, haz clic en el interruptor Habilitar/Inhabilitar para activarlo.
2. Haz clic en Guardar. Un interruptor verde confirma que se ha completado correctamente. Las credenciales de Marketplace se transfieren a ArmisManager. Si la auth se completa sin errores, el botón Prueba muestra una marca de verificación verde.

Usa el método extract_configuration_param para importar parámetros de la configuración de la integración. También puedes usar extract_action_param para definir parámetros en la propia acción. Sin embargo, la acción Ping siempre debe usar parámetros de configuración, ya que el Marketplace los prueba.

Ver integraciones personalizadas

Ve a Google SecOps Marketplace y busca la integración personalizada que has creado. Si no creaste una imagen durante la configuración inicial, se le asignará la imagen personalizada predeterminada. Ten en cuenta que las actualizaciones de Google SecOps Marketplace no sobrescriben ni eliminan ninguna integración personalizada.

Exportar e importar en el IDE

Lleva a cabo una de las acciones siguientes:

• Para importar integraciones, sigue estos pasos:
1. Sube un archivo ZIP con la estructura de carpetas correcta. La integración aparecerá en el IDE y en Google SecOps Marketplace.
2. Haz clic en Importar. La integración aparece tanto en el IDE como en Marketplace.
3. El sistema genera un archivo ZIP que contiene la definición, las secuencias de comandos y la configuración. La carpeta Gestores no se incluye automáticamente.
• Para exportar integraciones, sigue estos pasos:
• Haz clic en Exportar para descargar el paquete.

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