Crea un conector personalizado

Se admite en los siguientes sistemas operativos:

Google SecOps SOAR

Nota: En este documento, se supone que tienes conocimientos prácticos de Python y de programación orientada a objetos.

Usa este documento para aprender cómo el SDK de SOAR compila integraciones personalizadas para herramientas de terceros que tal vez no estén disponibles en el Centro de contenido. Los conectores se usan para ingerir datos de fuentes de datos que, por lo general, pero no siempre, tienen algún tipo de cola de alertas. Los casos, las alertas y los eventos se crean en la plataforma a través de la interacción del conector con la aplicación de Google SecOps. Un conector transferirá los datos básicos del evento, los asignará a una alerta y, luego, enviará la alerta a la aplicación de Google SecOps y a su canalización de procesamiento de datos.

Nota: Obtén más información sobre la biblioteca común de TIP.

Para crear un conector personalizado, sigue estos pasos generales:

1. Crea una clase Manager que contenga la lógica de la API para la herramienta externa.
2. Compila el conector con el IDE.

Crea el administrador

El primer paso para crear un conector es compilar una clase Manager que contenga toda la lógica de la API requerida para la tecnología con la que te integrarás. Como ejemplo, la integración de Netskope en Google SecOps incluye un administrador prediseñado. Este administrador contiene toda la lógica necesaria para interactuar con la API de Netskope y se puede usar como modelo para tu propia implementación.

Crea el conector

En el IDE, crea un conector nuevo siguiendo las instrucciones que se indican en Cómo compilar una integración personalizada. El IDE generará una plantilla genérica que incluye comentarios de código que describen la estructura y los requisitos básicos de una secuencia de comandos del conector.

Si bien la lógica del conector puede variar, el proceso generalmente incluye estos pasos principales:

1. Usa la API de la herramienta de terceros para recuperar alertas, detecciones o eventos. En el caso de Netskope, esto se controla con el método get_alerts(). Para asegurarte de que no se dupliquen las alertas, envía una consulta por marca de tiempo y actualízala después de cada ejecución.
2. Compila una alerta con la clase AlertInfo (anteriormente CaseInfo) y asigna todos los campos obligatorios.
3. Recupera y aplana los datos de eventos asociados para evitar problemas con listas y diccionarios anidados, y, luego, agrega los eventos aplanados a la alerta.
4. Ordena las alertas por hora y almacena la marca de tiempo más reciente para usarla en la próxima consulta.

Nota: Una alerta puede contener varios eventos. Por ejemplo, las plataformas de SIEM correlacionan varios eventos en una sola alarma (como Trellix ESM) o infracción (como QRadar). En cambio, las herramientas de detección de extremos suelen generar un evento por alerta. La lógica de tu conector debe reflejar la estructura de la fuente de datos.

Importaciones y el SDK

Todos los conectores deben hacer lo siguiente:

• Importa la clase SiemplifyConnectorExecution desde SiemplifyConnectors. Por lo general, esta clase se instancia en la función main() del conector. La secuencia de comandos finaliza cuando este objeto pasa una lista de alertas a la aplicación de SecOps de Google con el método return_package().
• Importa la clase AlertInfo desde SiemplifyConnectorsDataModel. La creación de una instancia de esta clase crea el objeto de alerta. En este ejemplo, se cambió el nombre a SiemplifyAlertInfo para evitar confusiones con los objetos de alerta integrados del sistema fuente (Netskope), donde este cambio de nombre es opcional.

El módulo SiemplifyUtils proporciona métodos de uso frecuente para el registro, el manejo de formatos de datos, las conversiones de tiempo y mucho más. Te recomendamos que importes output_handler, dict_to_flat y unix_now, ya que son esenciales para la funcionalidad principal, incluido el control del tiempo.

La mayoría de los conectores también importan la clase Manager de la integración. Algunas integraciones incluyen más de un administrador. También se pueden importar bibliotecas estándar de Python adicionales, según tu caso de uso.

Nota: Los conectores más antiguos pueden usar CaseInfo de SiemplifyConnectors. Esta es la misma clase que AlertInfo y refleja una convención de nomenclatura obsoleta.

Variables constantes

Es una buena práctica declarar algunas variables constantes para su uso posterior.

Figura 1: Variables constantes

Ejemplo de secuencia de comandos para crear la alerta de Google SecOps

Para crear una alerta, se crea una instancia de un objeto de la clase AlertInfo, como se explicó anteriormente. En este ejemplo, se cambió el nombre a SiemplifyAlertInfo() para evitar confusiones con el sistema fuente. El objeto alert_info incluye varias propiedades obligatorias que se deben definir para que la aplicación procese correctamente la alerta. La función build_alert_info recibe una alerta de Netskope (en formato JSON sin procesar, recibida de la API) y el objeto Siemplify como entradas. Luego, analiza la alerta de Netskope y asigna los valores pertinentes a los campos de `alert_info`.

Esta función también usa constantes definidas previamente. Todas las propiedades establecidas en el objeto alert_info pasan a formar parte del objeto de alerta dentro de la aplicación de Google SecOps.

La línea 35 (en la Figura 2) destaca una parte importante de este proceso: la alerta se aplana con el método dict_to_flat y, luego, se agrega a la propiedad events.

Figura 2: Ejemplo de secuencia de comandos para crear una alerta

 

Una alerta puede contener varios eventos. Si es así, debes incluir lógica para controlar cada evento de forma adecuada. En este ejemplo, cada alerta contiene solo un evento, por lo que la implementación predeterminada es suficiente.

El método dict_to_flat se usa para aplanar la estructura JSON sin procesar. Esto ayuda a evitar problemas con listas y diccionarios anidados. Los pares clave-valor aplanados son versiones ligeramente modificadas de los originales.

Revisa la siguiente lógica en la Figura 2:

• A display_id se le asigna un valor generado de forma aleatoria con la biblioteca uuid. Las alertas de Netskope no proporcionan un campo UUID, pero, si hubiera uno disponible, se podría usar en su lugar.
• ticket_id se configura para que coincida con display_id. Ambos campos deben ser únicos por alerta en el sistema. Esta unicidad se garantiza generando un UUID aleatorio.
• name es el nombre de la alerta y se mostrará en la GUI.
• rule_generator hace referencia a la regla que generó la alerta en el sistema de origen. Es posible que este campo no siempre esté presente en los datos sin procesar. Si falta, puedes asignar cualquier valor de cadena, pero no debe quedar vacío.
• start_time y end_time representan las marcas de tiempo de la alerta. En este ejemplo, la alerta de Netskope proporciona una marca de tiempo de época de Unix, que se debe multiplicar por 1,000 para convertirla en milisegundos. Este es el formato esperado para Google SecOps. Si la fuente usa un formato diferente, debes convertirlo. Consulta el módulo SiemplifyUtils.py para obtener métodos útiles de conversión de tiempo.
• priority: La aplicación de Google SecOps asigna una prioridad a cada caso según la prioridad de su alerta. La API de Google SecOps asigna valores numéricos a las etiquetas visuales con el siguiente esquema, en el que el valor entero se pasa en el conector: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}, donde el valor entero es lo que se pasa en el conector. Por ejemplo, si pasas el valor "100", la alerta se marcará como Crítica en la GUI. En este conector, una función de ayuda adicional asigna los valores de gravedad de Netskope a esta escala de prioridad con la constante "SEVERITY_MAP". Sin embargo, debido a que los campos de gravedad de Netskope son incoherentes, la asignación requiere lógica adicional para evaluar varios campos.
• A device_vendor y device_product se les asignan valores de constantes definidas anteriormente en la secuencia de comandos.
• environment es fundamental cuando se usan varios entornos en Google SecOps. En este caso, proviene del objeto siemplify y se alinea con el entorno seleccionado para el conector en la plataforma.
• En la línea 37 (figura 3), el conector modifica el diccionario de eventos base agregando una clave nueva, product_name, con el valor "Netskope". Esto es necesario porque los datos sin procesar no incluyen un campo de producto coherente que se pueda usar para la asignación y el modelado en la ontología de la plataforma.

  

  Figura 3: Modificación del evento base

Ejemplo de secuencia de comandos para ejecutar el conector

La función main contiene la lógica de ejecución principal del conector:

• El decorador output_handler se usa para la depuración y no se explica en este documento.
• La función main incluye un parámetro opcional, is_test_run, que, de forma predeterminada, es False. Como su nombre lo indica, este parámetro determina si el conector debe ingerir alertas en producción o ejecutarse en modo de prueba desde la pestaña Prueba de conector en la aplicación.

Revisa el desglose de la lógica de ejecución principal por línea de secuencia de comandos:

Figura 3: Modificación del evento base

• Las líneas 56 y 57 inicializan dos listas vacías que se usan durante la ejecución.
• En la línea 58, la clase SiemplifyConnectorExecution crea una instancia del objeto siemplify. Este objeto administra la mayor parte del comportamiento del conector durante el tiempo de ejecución.
• En la línea 61, se crea una instancia de Lista de entidades permitidas del conector. Si bien no se usa en este conector, se usa comúnmente en otros conectores y no se analiza en esta guía.
• En las líneas 67 a 69, se definen variables para los parámetros del conector, como las credenciales de autenticación o la configuración.
• En la línea 71, se crea una instancia del objeto NetskopeManager y se pasan los parámetros pertinentes para permitir la autenticación correcta. En este ejemplo, no se muestra la lógica interna del administrador que controla la autenticación.
• En la línea 73, se recupera una marca de tiempo de un archivo local creado durante las ejecuciones anteriores del conector. Esta marca de tiempo se usa para evitar volver a procesar las mismas alertas.
• En las líneas 74 y 75, se controla el caso en el que el conector se ejecuta por primera vez y aún no se configuró la marca de tiempo (por ejemplo, cuando se establece de forma predeterminada en "0"). Dado que Netskope requiere la hora de la época de Unix y no acepta "0" como hora de inicio válida, se usa la función "unix_now" para recuperar la hora actual en milisegundos. Este valor se divide por "1,000" para convertirlo en segundos de época Unix. Luego, los horarios de inicio y finalización resultantes se pasan al método `get_alerts` en el administrador. Si bien muchas APIs solo aceptan una hora de inicio, la API de Netskope requiere horas de inicio y finalización para las consultas de alertas basadas en el tiempo.
Nota: El control de la hora y la marca de tiempo es uno de los aspectos más complejos de la creación de un conector. Diferentes sistemas de terceros devuelven marcas de tiempo en varios formatos, y es posible que algunos no admitan consultas basadas en el mismo formato que devuelven. Es fundamental comprender a fondo la API del sistema fuente.
• En la línea 77, se recupera una lista de alertas de Netskope. Si el conector se ejecuta en modo de prueba, solo se selecciona la última alerta de la lista (líneas 79 y 80).

Lógica de desbordamiento

Luego, el conector itera a través de las alertas recuperadas y crea una alerta a partir de cada una de ellas con la función build_alert_info definida anteriormente. Agrega cada alerta a la lista all_alerts, que se inicializó anteriormente. La siguiente parte de la lógica del conector controla el desbordamiento.
El desbordamiento es un mecanismo de umbral que evita que se ingieran demasiadas alertas en un período corto, en especial cuando las alertas comparten el mismo entorno, producto y generador de reglas. Si bien no es obligatorio, te recomendamos que implementes la lógica de desbordamiento como práctica recomendada para evitar la degradación del rendimiento.

Revisa el desglose de la lógica de desbordamiento por línea de secuencia de comandos en la Figura 4:

• En las líneas 104 y 105, si un alert no se clasifica como desbordamiento, se anexa a la lista de alertas para la transferencia.



Figura 4: Mecanismo de desbordamiento.

Cómo finalizar la ejecución del conector

Si el conector no se ejecuta en modo de prueba, la marca de tiempo debe actualizarse para reflejar la última alerta recuperada. Esto garantiza que no se vuelvan a ingerir las mismas alertas durante el próximo ciclo de ejecución. La lista all_alerts se ordena por marca de tiempo, de modo que incluso las alertas desbordadas contribuyen a determinar la marca de tiempo más reciente.

Revisa el desglose de la lógica de ejecución del conector por línea de secuencia de comandos en la figura 5:

• En la línea 126, se envía la lista de alertas que no se desbordaron a la aplicación, donde se crean y muestran en la GUI.
• En las líneas 128 a 131, se determina si el conector se ejecuta en modo de prueba. Para tomar esta decisión, se usan los argumentos del sistema que pasa la aplicación, por ejemplo, cuando se hace clic en Ejecutar el conector una vez en la pestaña Pruebas.
  

  

  Figura 5: Finalización de la ejecución del conector

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