Crear un conector personalizado

Disponible en:

SecOps de Google SOAR

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

Consulta este documento para saber cómo crea el SDK de SOAR integraciones personalizadas para herramientas de terceros que pueden no estar disponibles en el centro de contenido. Los conectores se usan para ingerir datos de fuentes de datos que suelen tener, aunque no siempre, algún tipo de cola de alertas. Los casos, las alertas y los eventos se crean en la plataforma mediante la interacción del conector con la aplicación Google SecOps. Un conector ingerirá datos de eventos básicos, los asignará a una alerta y, a continuación, enviará la alerta a la aplicación Google SecOps y a su canalización de tratamiento de datos.

Nota: Consulta 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 de la herramienta de terceros.
2. Compila el conector con el IDE.

Crear el administrador

El primer paso para crear un conector es crear una clase Manager que contenga toda la lógica de la API necesaria para la tecnología con la que vas a integrar el conector. Por ejemplo, la integración de Netskope en Google SecOps incluye un gestor precompilado. Este gestor contiene toda la lógica necesaria para interactuar con la API de Netskope y se puede usar como modelo para tu propia implementación.

Crear el conector

En el IDE, crea un conector siguiendo las instrucciones de Crear una integración personalizada. El IDE generará una plantilla genérica que incluye comentarios de código que describen la estructura básica y los requisitos de una secuencia de comandos de conector.

Aunque la lógica de los conectores puede variar, el proceso suele incluir estos pasos principales:

1. Usa la API de la herramienta de terceros para obtener alertas, detecciones o eventos. En el caso de Netskope, esto se gestiona con el método get_alerts(). Para asegurarte de que las alertas no se dupliquen, envía una consulta por marca de tiempo y actualízala después de cada ejecución.
2. Crea una alerta con la clase AlertInfo (antes CaseInfo) y asigna todos los campos obligatorios.
3. Recupera y aplana los datos de eventos asociados para evitar problemas con listas y diccionarios anidados. A continuación, añade 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 siguiente consulta.

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

Importaciones y SDK

Todos los conectores deben hacer lo siguiente:

• Importa la clase de SiemplifyConnectorExecution desde SiemplifyConnectors. Esta clase se suele crear en la función main() del conector. La secuencia de comandos finaliza cuando este objeto transfiere una lista de alertas a la aplicación Google SecOps mediante el método return_package().
• Importa la clase de AlertInfo desde SiemplifyConnectorsDataModel. Al crear una instancia de esta clase, se crea el objeto de alerta. En este ejemplo, se le cambia el nombre a SiemplifyAlertInfo para evitar confusiones con los objetos de alerta integrados del sistema de origen (Netskope), donde este cambio de nombre es opcional.

El módulo SiemplifyUtils proporciona métodos que se usan con frecuencia para registrar, gestionar formatos de datos, conversiones de tiempo y más. Te recomendamos que importes output_handler, dict_to_flat y unix_now, ya que son esenciales para las funciones principales, como la gestión 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, en función de tu caso práctico.

Nota: Los conectores antiguos pueden usar CaseInfo de SiemplifyConnectors. 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 usarlas más adelante.

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 ha explicado anteriormente. En este ejemplo, se le ha cambiado el nombre a SiemplifyAlertInfo() para evitar confusiones con el sistema de origen. El objeto alert_info incluye varias propiedades obligatorias que deben definirse 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. A continuación, analiza la alerta de Netskope y asigna los valores correspondientes a los campos `alert_info`.

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

La línea 35 (en la figura 2) destaca una parte importante de este proceso: la alerta se acopla mediante el método dict_to_flat y, a continuación, se añade 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 gestionar 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 formato. De esta forma, se evitan problemas con listas y diccionarios anidados. Los pares clave-valor simplificados 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 aleatoriamente mediante la biblioteca uuid. Las alertas de Netskope no proporcionan un campo UUID, pero, si estuviera disponible, se podría usar en su lugar.
• ticket_id se ha configurado para que coincida con display_id. Ambos campos deben ser únicos por alerta en el sistema. Esta singularidad se garantiza generando un UUID aleatorio.
• name es el nombre de la alerta y se mostrará en la interfaz gráfica de usuario.
• rule_generator hace referencia a la regla que ha generado la alerta en el sistema de origen. Este campo no siempre está presente en los datos sin procesar. Si falta, puede asignar cualquier valor de cadena, pero no debe dejarlo 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 debe multiplicarse por 1000 para convertirla en milisegundos. Este es el formato esperado para Google SecOps. Si la fuente usa un formato diferente, debe convertirlo. Consulta el SiemplifyUtils.pymódulo para ver métodos útiles de conversión de tiempo.
• priority: la aplicación Google SecOps asigna una prioridad a cada caso en función de la prioridad de su alerta. La API Google SecOps asigna valores numéricos a las etiquetas visuales mediante el siguiente esquema, en el que se pasa el valor entero 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 se introduce el valor `100`, la alerta se marcará como Crítica en la interfaz gráfica de usuario. En este conector, una función auxiliar adicional asigna los valores de gravedad de Netskope a esta escala de prioridad mediante la constante `SEVERITY_MAP`. Sin embargo, como los campos de gravedad de Netskope no son coherentes, la asignación requiere una 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, procede del objeto siemplify y se corresponde con el entorno seleccionado para el conector en la plataforma.
• En la línea 37 (imagen 3), el conector modifica el diccionario de eventos base añadiendo una nueva clave, 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 la modelización en la ontología de la plataforma.

  

  Imagen 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 con fines de depuración y no se trata en este documento.
• La función main incluye un parámetro opcional, is_test_run, que tiene el valor predeterminado False. Como su nombre indica, este parámetro determina si el conector debe ingerir alertas en producción o ejecutarse en modo de prueba desde la pestaña Pruebas de conectores de la aplicación.

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

Imagen 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 gestiona la mayor parte del comportamiento del conector en tiempo de ejecución.
• En la línea 61, se crea una instancia de Connector Allowlist. Aunque no se usa en este conector, se suele usar en otros conectores y no se explica en esta guía.
• En las líneas 67-69, se definen variables para los parámetros del conector, como las credenciales de autenticación o los ajustes de configuración.
• En la línea 71, se crea una instancia del objeto NetskopeManager y se le transfieren los parámetros pertinentes para que la autenticación se realice correctamente. La lógica interna de Manager que gestiona la autenticación no se muestra en este ejemplo.
• En la línea 73, se obtiene una marca de tiempo de un archivo local creado durante las ejecuciones anteriores del conector. Esta marca de tiempo se usa para evitar que se vuelvan a procesar las mismas alertas.
• En las líneas 74 y 75, se gestiona el caso en el que el conector se ejecuta por primera vez y la marca de tiempo aún no se ha definido (por ejemplo, cuando el valor predeterminado es `0`). Como 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 obtener la hora actual en milisegundos. Este valor se divide entre `1000` para convertirlo a segundos de época Unix. Las horas de inicio y de finalización resultantes se transfieren al método `get_alerts` del gestor. Aunque muchas APIs solo aceptan una hora de inicio, la API de Netskope requiere tanto la hora de inicio como la de finalización para las consultas de alertas basadas en el tiempo.
Nota: La gestión 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 conocer a fondo la API del sistema de origen.
• En la línea 77, se obtiene una lista de alertas de Netskope. Si el conector se está ejecutando en modo de prueba, solo se selecciona la última alerta de la lista (líneas 79-80).

Lógica de desbordamiento

A continuación, el conector itera por las alertas obtenidas y crea una alerta a partir de cada una de ellas mediante la función build_alert_info definida anteriormente. Añade cada alerta a la lista all_alerts, que se ha inicializado anteriormente. La siguiente parte de la lógica del conector gestiona el desbordamiento.
El desbordamiento es un mecanismo de umbral que evita que se ingieran demasiadas alertas en un breve periodo, sobre todo cuando las alertas comparten el mismo entorno, producto y generador de reglas. Aunque no es obligatorio, te recomendamos que implementes la lógica de desbordamiento como práctica recomendada para evitar que el rendimiento se vea afectado.

Consulta 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 añade a la lista de alertas que se van a ingerir.



Imagen 4: Mecanismo de desbordamiento.

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. De esta forma, se asegura que las mismas alertas no se vuelvan a ingerir durante el siguiente ciclo de ejecución. La lista all_alerts se ordena por marca de tiempo para que incluso las alertas que se hayan desbordado contribuyan a determinar la marca de tiempo más reciente.

Consulta el desglose de la lógica de ejecución del conector por línea de script en la figura 5:

• En la línea 126, la lista de alertas que no se han desbordado se envía a la aplicación, donde se crean y se muestran en la interfaz gráfica de usuario.
• En las líneas 128-131, se determina si el conector se está ejecutando en modo de prueba. Para determinarlo, se usan los argumentos del sistema que transmite la aplicación, como cuando se hace clic en Ejecutar conector una vez en la pestaña Pruebas.
  

  

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

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