Desarrollo de una solución de cuadernos para Microsoft Sentinel

Como socio ISV, puede crear, probar, empaquetar y publicar soluciones de análisis de cuadernos de Jupyter en Seguridad de Microsoft Store como ofertas de SaaS. El lago de datos de Microsoft Sentinel es compatible con cuadernos de Jupyter que se ejecutan en grupos de Spark administrados con grandes conjuntos de datos de seguridad. Estos cuadernos son ideales para la detección de ataques lentos y de bajo perfil, el establecimiento de líneas base de comportamiento, los análisis basados en IA/ML, la asignación de rutas de acceso a datos sensibles, las visualizaciones de datos y el enriquecimiento de datos que las detecciones tradicionales en KQL no pueden expresar.

Una solución de plataforma de cuadernos suele estar diseñada para análisis históricos, transformaciones complejas de datos y flujos de trabajo recurrentes de procesamiento de datos. Escribe la salida en una tabla personalizada del lago de datos, donde las reglas analíticas posteriores, las consultas de detección, los agentes de Security Copilot o las herramientas MCP pueden consumir los resultados de la solución del cuaderno. El paquete .zip que envía al Centro de partners se declara con el tipo SentinelLake y contiene los cuadernos y, opcionalmente, una plantilla de ARM para los recursos posteriores de Azure que necesita el cuaderno de notas.

Este artículo te guía en la construcción, prueba, empaquetado y publicación de una solución de portátil de la plataforma Microsoft Sentinel para la Seguridad de Microsoft Store. Después de completar esta guía, tendrá lo siguiente:

Un cuaderno de Jupyter funcional que lee datos del lago de datos de Sentinel
Un trabajo programado que ejecuta el cuaderno en un grupo de Spark administrado
Un SentinelLake paquete ZIP (PackageManifest + carpeta de notebooks)
Una descripción de la oferta de SaaS del Centro de partners en la Tienda Seguridad de Microsoft

Prerequisites

Su tenant debe estar integrado en el lago de datos de Microsoft Sentinel. Compruebe el estado de incorporación en el portal de Defender. Vaya aConfiguración del>sistema>Microsoft Sentinel>Lago de datos. El estado lee Aprovisionado si el inquilino está listo. Para obtener instrucciones de incorporación, consulte Incorporación al lago de datos de Microsoft Sentinel.

Permisos necesarios

Operación/Recursos	Rol obligatorio
Incorpórese al lago de datos Sentinel	Microsoft Entra ID: administrador de seguridad o administrador global
Incorporación del área de trabajo de Sentinel al portal de Defender	Propietario de la suscripción, o Administrador de acceso de usuario en el ámbito de la suscripción y Colaborador de Microsoft Sentinel en el ámbito de la suscripción o del grupo de recursos
Incorporar el área de trabajo de Sentinel al lago de datos	Propietario de la suscripción o colaborador de Microsoft Sentinel en el ámbito de la suscripción o del grupo de recursos
Ejecución de cuadernos en el lago de datos	lector o colaborador de Microsoft Sentinel
Área de trabajo de análisis de registros (para la escritura en la capa analítica)	Colaborador de Log Analytics asignado a la identidad administrada de data lake `msg-resources-<guid>`
Centro de partners de Microsoft	Cuenta de publicador de Marketplace (solo una vez; la misma cuenta utilizada para la publicación de agentes de Copilot for Security)

Note

Se requiere el rol de propietario de la suscripción para una tarea única de integración del lago de datos. Use Microsoft Entra Privileged Identity Management (PIM) para elevar temporalmente este rol solo cuando sea necesario y, después, quite el acceso una vez completada la incorporación.

Herramientas necesarias

Código de Visual Studio.
Extensión de VS Code para Microsoft Sentinel
Se recomienda la extensión de GitHub Copilot para VS Code para agilizar la creación de cuadernos.
Python 3.10+ instalado localmente. El kernel de Spark se ejecuta en Azure, pero VS Code necesita un intérprete local para la edición de celdas.

Visión general del proceso

El proceso de publicación comienza con el desarrollo local de cuadernos y pasa a una oferta SaaS empaquetada disponible en Seguridad de Microsoft Store.

Desarrollo de cuadernos locales (extensión VS Code + Sentinel)
Ejecución interactiva en la plataforma Sentinel
Pruebe con datos representativos; valide que la tabla de salida se rellene correctamente
Programación como trabajo (a petición o programado)
Empaquetar como SentinelLake .zip (PackageManifest.yaml + carpeta)
Creación de una oferta de SaaS en Microsoft Partner Center
Carga del paquete, creación de metadatos, plan y precios
Revisión y publicación, revisión automatizada, Go Live
Ya disponible en la tienda de Seguridad de Microsoft

Instalar Visual Studio Code y la extensión Microsoft Sentinel

Todo el desarrollo de cuadernos se lleva a cabo localmente en VS Code con la extensión de Microsoft Sentinel instalada. El kernel de Spark se ejecuta en Azure: VS Code es el editor y el cliente de envío.

Descargue Visual Studio Code desde https://code.visualstudio.com/ e instale con opciones predeterminadas.
Abra el marketplace de >Extensiones de VS Code (Ctrl+Mayús+X o Cmd+Mayús+X).
Busque Sentinel e instale la extensión Microsoft Sentinel (publicador: ms-security).

Después de la instalación, el icono de Microsoft Sentinel aparece en la barra de herramientas izquierda.
(Recomendado) Busque GitHub Copilot en Marketplace, instálelo e inicie sesión en GitHub cuando se le solicite.

Copilot conoce la MicrosoftSentinelProvider API y autocompleta las transformaciones de PySpark.
Seleccione el icono Microsoft Sentinel de la barra de herramientas izquierda.
Acepte el cuadro de diálogo de inicio de sesión y, a continuación, seleccione la cuenta con Sentinel Reader / Contributor en su área de trabajo.

El panel izquierdo muestra Tablas del lago y Tareas, lo que confirma que la extensión ha llegado al lago de datos.

Caution

Si tienes varios inquilinos invitados conectados, al cambiar de cuenta en la esquina inferior izquierda de VS Code se cierran todas las sesiones activas de PySpark; tendrás que reiniciar el kernel después de realizar el cambio. Planifica los cambios de cuenta entre ejecuciones, no durante las mismas.

Desarrolla tu cuaderno

Los cuadernos siguen este patrón de creación:

Leer una tabla de un lago de datos en un DataFrame de Spark
Transformación con PySpark
Opcionalmente, enriquecer con datos externos
Escritura de resultados en una tabla personalizada que Sentinel puede consumir

Explorar el panel de tablas de Lake

Para identificar las tablas de entrada que usa el cuaderno, explore el panel Tablas de Lake:

Seleccione el icono de Sentinel y expanda Tablas de Lake.
Las tablas se agrupan por base de datos y categoría (Sistema, Personalizado, Federado). Seleccione cualquier tabla para ver sus definiciones y tipos de columna.
Identifique las tablas de entrada que lee el cuaderno y anote los nombres exactos.

Crea un nuevo cuaderno

Para crear un cuaderno de Jupyter Notebook para la solución, complete los pasos siguientes:

Presione Ctrl+Mayús+P / Cmd+Mayús+P>, escriba Create New Jupyter Notebook o seleccione Archivo>Nuevo archivo>Jupyter Notebook.
Guarde el cuaderno con un nombre descriptivo (por ejemplo, failed-signin-baseline.ipynb).

Leer una tabla

Pegue esta plantilla en la primera celda y reemplace el nombre de la tabla por el suyo:

from sentinel_lake.providers import MicrosoftSentinelProvider
data_provider = MicrosoftSentinelProvider(spark)

# Read a table from the data lake
table_name = "EntraGroups"
df = data_provider.read_table(table_name)

# Quick sanity check—show 100 rows
df.select("displayName", "groupTypes", "mail", "tenantId").show(100, truncate=False)

Selecciona un grupo de entornos de ejecución y ejecuta la celda

Para ejecutar la celda en el lago de datos, selecciona un grupo y envía la orden:

Selecciona el triángulo Ejecutar en la celda.
Cuando se le solicite, elija Microsoft Sentinel como tiempo de ejecución.
Elija un tamaño de grupo: Pequeño para la exploración, Medio para transformaciones, Grande para ML o agregaciones en decenas de millones de filas.

La primera ejecución tarda entre 3 y 5 minutos en iniciar la sesión de Spark. Las celdas posteriores se ejecutan en segundos.

Transforme y vuelva a escribir en una tabla personalizada

El método save_as_table() escribe un DataFrame en una tabla personalizada en el nivel del lago de datos (o nivel de análisis). La tabla de destino se crea en la primera escritura.

df_transformed = (
    df.filter(df.mail.isNotNull())
    .select("displayName", "groupTypes", "mail", "mailNickname", "description", "tenantId")
)

write_options = {"mode": "overwrite"}
data_provider.save_as_table(
    df_transformed,
    "EntraGroups_Processed_SPRK",
    write_options=write_options,
)

Patrones de creación de cuadernos

Los siguientes patrones cubren los escenarios más comunes:

Pattern	Cuándo usarlo
Línea base + desfase	Calcule el comportamiento normal por usuario o por host; marque las filas que se desvían de la referencia. Es un método clásico para el análisis de inicios de sesión fallidos y de ejecución de procesos.
Unión entre tablas	Une la tabla del lago de datos de la que eres propietario con tablas integradas (SigninLogs, SecurityAlert, DeviceProcessEvents) en función de entidades compartidas (UPN, host, IP).
Puntuación de ML	Entrena o carga un modelo preentrenado en el cuaderno; evalúa cada fila; escribe las N filas de mayor riesgo en una tabla de salida personalizada para generar alertas posteriores.
Investigación visual	Traza líneas de tiempo, mapas de calor y árboles de procesos con matplotlib o plotly; exporta el cuaderno como HTML para su entrega.

Tip

Use las celdas markdown liberalmente para documentar el código. Un revisor de Security Store (y el analista de SOC que ejecuta el cuaderno) debe comprender lo que hace cada sección sin leer el código. Coloque una celda markdown encima de cada bloque de código que explique el propósito, las entradas, las salidas y la salida esperada. Los revisores consideran los cuadernos poco claros como un error grave.

Prueba el portátil

Las pruebas requieren probar que el cuaderno ejecuta datos realistas de un extremo a otro y genera una tabla de salida utilizable.

Prueba de funcionamiento en un grupo pequeño

Ejecuta el cuaderno de principio a fin para confirmar que todas las celdas se completan sin errores:

Reinicie el kernel para borrar cualquier estado obsoleto.
Ejecute todas las celdas de arriba a abajo: todas las celdas deben completarse sin errores.

Si una celda de transformación tarda más de 5 minutos en el entorno Small, tus filtros de entrada son demasiado laxos. Restringe la proyección de fechas o columnas antes de ampliar la escala.

Validación de la tabla de salida

Confirme que se creó la tabla de salida y contiene los datos esperados:

En el panel Tablas de Lake de la extensión de Sentinel, actualice y confirme que la tabla de salida aparezca con el esquema esperado.
Ejecute una celda de comprobación:

verify_df = data_provider.read_table("EntraGroups_Processed_SPRK")
print("Row count:", verify_df.count())
verify_df.printSchema()
verify_df.show(5, truncate=False)

Prueba de escalabilidad en un conjunto mediano o grande

Compruebe que el cuaderno genera resultados coherentes en tamaños de grupo mayores:

Vuelva a ejecutar el cuaderno con el tamaño mediano (y el grande si el conjunto de datos lo requiere).
Comprueba que el recuento de filas y la distribución de columnas coincidan con la ejecución en el entorno Small. Si divergen, hay una transformación no determinista que debe investigarse.

Casos límite de prueba

Entrada vacía: apunte a una tabla o intervalo de fechas con cero filas. El cuaderno debería fallar de forma controlada o generar una salida vacía, pero no bloquearse.
Desviación del esquema: si a tu tabla de entrada se le añade una columna, el cuaderno debería seguir ejecutándose. No dé por sentado el orden de posición.

Programe el cuaderno como una tarea

La mayoría de las soluciones de cuadernos publicadas se ejecutan según una programación: línea de base horaria, análisis diario de anomalías, etc. La extensión de Sentinel convierte cualquier cuaderno guardado en un trabajo programado que se ejecuta desatendido en un grupo de Spark administrado.

Creación del trabajo

Para convertir el cuaderno en un trabajo programado, complete los pasos siguientes:

Abra el cuaderno en VS Code.
Seleccione Crear trabajo de programación en el cuaderno y, después, elija Usar cuaderno existente cuando se le solicite.

Para obtener más información, consulte Creación y administración de trabajos de Jupyter Notebook.

Configuración del trabajo

Para configurar el trabajo programado, rellene los campos siguientes:

Introduce un nombre de trabajo en mayúsculas y minúsculas mezcladas que describa el cuaderno (por ejemplo, failed-signin-baseline-hourly).
Escriba una descripción de una frase que abarque el propósito y la tabla de salida del trabajo.
Seleccione el tamaño del grupo de Spark que validó durante las pruebas. No lo sobredimensiones: los trabajos se ejecutan en este grupo en cada invocación.
En Programación, elija A petición para ejecuciones manuales o Programada con una frecuencia de repetición (minuto, hora, diaria, semanal o mensual).
Seleccione Enviar para publicar el trabajo.

Comprobación del trabajo

Después de enviar, confirme que el trabajo se está ejecutando correctamente:

Vaya al panel Jobs de la extensión Sentinel: su tarea debería aparecer.
Seleccione el trabajo >Ejecutar ahora para una ejecución de validación inmediata.
Una vez completada la ejecución, cambie a la pestaña Historial de ejecución para inspeccionar los registros y el tiempo.

Importante

Los trabajos enviados se desacoplan del archivo local .ipynb . La edición del archivo local no actualiza el trabajo en ejecución. Para actualizar un trabajo: ábralo en el panel Trabajos>Descargar el cuaderno> edite >Editar trabajo>Enviar para cargar la versión actualizada.

Visualización del trabajo en el portal de Defender

Vaya a Microsoft Sentinel>Exploración del lago de datos>Trabajos. Puede habilitar o deshabilitar la programación y ver el historial de ejecución aquí, pero no puede editar el cuaderno desde el portal.

Empaqueta y publica tu solución de cuaderno

Una vez que hayas probado y materializado tu cuaderno, empaquétalo para su implementación en los clientes. Para obtener instrucciones detalladas sobre el empaquetado, consulte Empaquetar y publicar soluciones de grafos y cuadernos de Microsoft Sentinel.

Troubleshooting

Creación de cuadernos

Síntoma	Causa y corrección probables
`MicrosoftSentinelProvider` no encontrado	La extensión no ha iniciado sesión o ha abierto un kernel que no es de Spark. Inicie sesión en la extensión Microsoft Sentinel y seleccione el Microsoft Sentinel runtime cuando se le solicite.
La celda se queda bloqueada en Iniciando sesión de Spark	El inicio de la primera celda tarda entre 3 y 5 minutos. Después de 6 minutos, compruebe el indicador de utilización de vCore en la barra de estado: es posible que el grupo haya alcanzado su capacidad máxima. Pruebe un tamaño de pool más pequeño.
`save_as_table` falla con un error de permiso denegado en el nivel de análisis	La identidad administrada del lago de datos `msg-resources-<guid>` no tiene Log Analytics Contributor en el espacio de trabajo de Log Analytics. Asígnelo según los requisitos previos y vuelva a intentarlo.
La tabla de salida aparece en el panel tablas de Lake, pero está vacía	Un `.filter()` probablemente eliminó todas las filas. Añade una impresión del recuento de filas inmediatamente antes de `save_as_table` para localizar el problema.

Para obtener más información, consulte Solución de problemas de Notebooks.

Programación de trabajos

Síntoma	Causa y corrección probables
Los cambios en el entorno local `.ipynb` no se reflejan en la tarea programada	Los trabajos enviados se desacoplan del archivo local. Descargue el trabajo de VS Code, edítelo y, a continuación, use Editar trabajo>Enviar para subir la nueva versión.
La tarea se ejecuta, pero no genera ninguna salida	Consulte la pestaña Historial de ejecuciones en el panel Trabajos; el registro de ejecución suele mostrar la celda que falla. La causa más habitual es que el cuaderno lea desde una tabla a la que la identidad en ejecución no tiene acceso.