Compila integraciones personalizadas

Compatible con:

Google SecOps SOAR

En este documento, se explican los flujos de trabajo para compilar integraciones personalizadas para Google SecOps. La práctica recomendada actual es desarrollar integraciones de forma local con el IDE que prefieras y administrarlas a través de GitHub con flujos de trabajo modernos de GitOps. Para entornos heredados o prototipos rápidos, también puedes compilar integraciones directamente en el IDE de SOAR integrado.

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

IDE local y flujo de trabajo de GitHub (recomendado)

El flujo de trabajo recomendado es desarrollar integraciones de forma local y administrarlas a través de GitHub. Este enfoque se alinea con las prácticas modernas de GitOps, lo que permite un mejor control de versión, colaboración y administración automatizada de dependencias.

Para obtener pasos técnicos detallados, guías de instalación y comandos modernos con la herramienta Marketplace CLI y el administrador de paquetes uv, consulta el repositorio de GitHub oficial de Chronicle Content Hub.

Descripción general del flujo de trabajo conceptual

Para desarrollar integraciones personalizadas de forma local, se recomienda que sigas este ciclo de vida de GitOps. Para conocer la sintaxis exacta y actualizada de estos comandos, consulta la documentación oficial de la CLI de MP en GitHub.

1. Bifurca y clona: Clona el repositorio oficial de content-hub en tu máquina de desarrollo local.
2. Instala las herramientas: Instala la herramienta de la CLI de mp y el administrador de paquetes de Python uv.
3. Autenticación: Accede a tu entorno de Google SecOps a través de la CLI de MP con la URL de tu instancia y las claves de API.
4. Desarrolla de forma local: Usa tu IDE preferido (como VS Code o PyCharm) para escribir tu código de integración, aprovechando las herramientas locales de depuración y prueba.
5. Administra dependencias: Usa uv para declarar y administrar dependencias (como TIPCommon) en tu archivo pyproject.toml local.
6. Sincroniza: Usa los comandos mp pull y mp push para sincronizar tu código local con tu instancia de Google SecOps para pruebas y la implementación.

Alternativa: Crea una integración personalizada en el IDE integrado

Si mantienes integraciones heredadas, pruebas una secuencia de comandos rápidamente o trabajas en un entorno en el que el desarrollo local está restringido, puedes usar el IDE integrado.

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 Respuesta > 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 con la opción Configuración Configuración, lo que indica que es una integración personalizada.

Haz clic en settings 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 bibliotecas, independientemente de lo que esté instalado en el sistema subyacente.

Si usas un archivo .WHL personalizado o de propiedad exclusiva (como TIPCommon) que requiere subdependencias anidadas, debes subir manualmente archivos wheel individuales para todo el árbol de dependencias antes de guardar. Si no se resuelven las dependencias anidadas, se produce un error genérico de errorCode: 2000. Para un seguimiento de dependencias avanzado, considera usar el IDE local y el flujo de trabajo de GitHub.

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 crearlas, impórtalas 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 una 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 de Google SecOps Content Hub. Los parámetros incluyen lo siguiente:

• Raíz de la API: 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 Verify SSL: Si está habilitada, verifica que el certificado SSL para la conexión con el 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 se habilita esta opción, 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: Haz clic siempre 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 Probar falla y muestra una X roja.

Implementa una acción de ping

La lógica de la acción Ping actúa como una autenticación correcta.

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 Respuesta > 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. Un botón de activación verde confirma que se realizó correctamente. Las credenciales del Content Hub se pasan a ArmisManager. Si auth se completa sin errores, el botón Probar 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. 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 Content Hub los prueba.

Ver 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 de Content Hub no anulan ni borran ninguna integración personalizada.

Cómo 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 Content Hub.
2. Haz clic en Importar. La integración aparece tanto en el IDE como en el Content Hub.
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.