Crea una integración personalizada

Se admite en los siguientes sistemas operativos:

Google SecOps SOAR

En este documento, se explica cómo crear integraciones personalizadas dentro del entorno de desarrollo integrado (IDE) con la misma estructura que las integraciones comerciales. Puedes encontrar y configurar integraciones personalizadas en el Centro de contenido para diversos entornos. Luego, puedes usarlos en guías, acciones manuales y agentes remotos. También se admite la capacidad de importar y exportar, de manera similar a otros elementos del IDE.

Nota: Para obtener un marco de desarrollo estandarizado, lineamientos de garantía de calidad y prácticas recomendadas para compilar y enviar integraciones personalizadas, consulta Prácticas recomendadas.

Crea una integración personalizada en el IDE

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

Caso de uso: Compila 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 Response > IDE.
2. Haz clic en Crear elemento nuevo y selecciona Integración.
3. Ingresa 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 mostrar la configuración de la integración, en la que puedes definir el ícono, la descripción, las dependencias de Python y los parámetros de integración.

Nota: Las dependencias de la secuencia de comandos son bibliotecas de Python que requiere tu integración personalizada. Las dependencias se pueden subir como archivos .WHL, .TAR, .GZ o .PY. Cada integración se ejecuta en su propio entorno virtual, lo que te permite usar versiones específicas de la biblioteca, independientemente de lo que esté instalado en el sistema subyacente. Por ejemplo, para usar una versión diferente de la biblioteca de solicitudes, descárgala de una fuente confiable, como PyPI o GitHub, y agrégala como una dependencia de secuencia de comandos.
Para las dependencias que requieren una rueda binaria precompilada (como los paquetes con extensiones C), la plataforma de SOAR usa cpython estándar compilado en la arquitectura manylinux_2_17_x86_64. Cuando selecciones un archivo .WHL, verifica que sea compatible con esta etiqueta.
Si no se instala una biblioteca en el entorno virtual, la integración recurre a la versión instalada en el sistema.

Si un paquete de dependencia no tiene un archivo wheel precompilado (.WHL) disponible para la arquitectura manylinux_2_17_x86_64, o si necesitas una versión específica del código fuente, puedes proporcionar una URL directa al código fuente (por ejemplo, un archivo .tar.gz). El solucionador de dependencias de la plataforma, uv, admite la definición de estas URLs de origen en la tabla [tool.uv.sources] dentro de tu archivo pyproject.toml. Por ejemplo:

[project]
# ... other project fields ...

[tool.uv.sources]
# The key (e.g., compressed-rtf) must match the dependency name
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Para obtener más detalles sobre cómo definir diferentes tipos de dependencias con uv, consulta la documentación de uv sobre cómo administrar dependencias.

Crea un administrador personalizado

Los administradores son wrappers para las APIs de herramientas de terceros. Aunque no son obligatorios, los recomendamos para las integraciones que interactúan con herramientas externas. Los administradores no deben importar desde el SDK. Después de crearlos, impórtalos a conectores, acciones y trabajos.

Para crear un administrador personalizado, sigue estos pasos:

1. En el IDE, haz clic en Create New Item y selecciona Manager.
2. Selecciona la integración de Armis y, luego, ingresa el nombre de un administrador.
   
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. Response) La respuesta que se validará
       :param error_msg: (str) El mensaje de error que se 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 se requiere un administrador para las acciones básicas. Sin embargo, te recomendamos que crees uno cuando agrupes acciones pequeñas para el análisis y la transformación de datos.

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

Los parámetros definidos en la configuración de la integración aparecen en la configuración del Centro de contenido de Google SecOps. Los parámetros incluyen lo siguiente:

• API Root: Es la URL base del servicio al que te conectas.
• Secreto de API: Es una clave confidencial que se usa para autenticar tu aplicación con el servicio.
• Casilla de verificación Verificar SSL: Si está habilitada, verifica que el certificado SSL para la conexión al servidor de Armis sea válido.
• Casilla de verificación Ejecutar de forma remota: Es un parámetro de configuración que determina si el código o la tarea se ejecutarán en un servidor remoto en lugar de hacerlo de forma local. Cuando esta opción está habilitada, el sistema envía las instrucciones y los datos necesarios a un servidor dedicado para su procesamiento.

Para actualizar los parámetros, sigue estos pasos:

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

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

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

Implementa una acción de Ping

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

Para implementar una acción de Ping, haz lo siguiente:

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

Habilita la integración

Para habilitar la integración, sigue estos pasos:

1. En Response > IDE, haz clic en el botón de activación o desactivación Habilitar/Inhabilitar para llevarlo a la posición ACTIVADO.
2. Haz clic en Guardar. El botón de activación verde confirma que la operación se realizó correctamente. Las credenciales del Centro de contenido se pasan a ArmisManager. Si auth se completa sin errores, el botón Probar mostrará una marca de verificación verde.

Usa el método extract_configuration_param para importar parámetros desde la configuración de la integración. Como alternativa, usa extract_action_param para definir parámetros dentro de la acción. Sin embargo, la acción Ping siempre debe usar parámetros de configuración, ya que el Centro de contenido los prueba.

Cómo ver las integraciones personalizadas

Ve al Centro de contenido y busca la integración personalizada que creaste. Si no creaste una imagen durante la configuración inicial, se le asignará la imagen personalizada predeterminada. Ten en cuenta que las actualizaciones del Centro de contenido no anulan ni borran las integraciones personalizadas.

Importar y exportar en el IDE

Realiza una de las siguientes acciones:

• Para importar integraciones, haz lo siguiente:
1. Sube un archivo ZIP con la estructura de carpetas correcta. La integración aparecerá en el IDE y en el Centro de contenido.
2. Haz clic en Importar. La integración aparece en el IDE y en el Centro de contenido.
3. El sistema genera un archivo ZIP que contiene la definición, las secuencias de comandos y la configuración. La carpeta Administradores no se incluye automáticamente.
• Para exportar integraciones, haz lo siguiente:
• Haz clic en Exportar para descargar el paquete.

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