Sviluppare una soluzione notebook per Microsoft Sentinel

In qualità di partner ISV, è possibile creare, testare, creare pacchetti e pubblicare soluzioni di analisi dei notebook jupyter nel Microsoft Security Store come offerte SaaS. Il data lake di Microsoft Sentinel supporta i Jupyter Notebook eseguiti su pool Spark gestiti con grandi set di dati di sicurezza. Questi notebook sono ideali per il rilevamento di attacchi lenti e a bassa intensità, la definizione di baseline comportamentali, l’analisi basata su IA/ML, la mappatura dei percorsi dei dati sensibili, la visualizzazione dei dati e gli arricchimenti che le tradizionali regole di rilevamento KQL non riescono a esprimere.

Una soluzione di piattaforma notebook è tipicamente progettata per analisi storiche, trasformazioni complesse di dati e flussi di lavoro ricorrenti di elaborazione dati. Scrive l’output in una tabella personalizzata nel data lake, dove regole analitiche downstream, query di ricerca, agenti Security Copilot o strumenti MCP possono utilizzare i risultati della soluzione notebook. Il pacchetto .zip inviato al Partner Center è dichiarato di tipo SentinelLake e contiene i notebook e, facoltativamente, un modello ARM per le risorse Azure downstream di cui il notebook necessita.

Questo articolo ti guida nella costruzione, test, confezionamento e pubblicazione di una soluzione notebook per la piattaforma Microsoft Sentinel sul Microsoft Security Store. Dopo aver completato questa guida, si avrà:

Notebook di Jupyter funzionante che legge i dati dal data lake di Sentinel
Processo pianificato che esegue il notebook in un pool Spark gestito
Un pacchetto ZIP SentinelLake (PackageManifest + cartella del notebook)
Presentazione di un'offerta SaaS del Centro per i partner nello Store Microsoft Security

Prerequisiti

Il tenant deve essere abilitato al data lake di Microsoft Sentinel. Verifica lo stato di onboarding nel portale Defender. Passare aImpostazioni>di sistema>Microsoft Sentinel>Data lake. Lo stato indica Provisioned se il tenant è pronto. Per istruzioni sull'onboarding, vedere Eseguire l'onboarding in data lake di Microsoft Sentinel.

Autorizzazioni necessarie

Operazione/Risorsa	Ruolo necessario
Eseguire l'onboarding al data lake di Sentinel	Microsoft Entra ID - Amministratore della sicurezza o Amministratore globale
Eseguire l'onboarding dell'area di lavoro Sentinel in Defender portal	Proprietario della sottoscrizione o Amministratore dell'accesso utente a livello di sottoscrizione e Collaboratore di Microsoft Sentinel a livello di sottoscrizione o di gruppo di risorse
Esegui l'onboarding dell'area di lavoro Sentinel in Data Lake	Proprietario della sottoscrizione o Collaboratore di Microsoft Sentinel a livello di sottoscrizione o gruppo di risorse
Eseguire i notebook nel data lake	Lettore o Collaboratore di Microsoft Sentinel
Area di lavoro analisi dei log (per il writeback al livello di analisi)	Collaboratore di Analisi dei log assegnato all'identità gestita del data lake `msg-resources-<guid>`
Centro per i partner Microsoft	Account editore di Marketplace (una sola volta; lo stesso account usato per la pubblicazione degli agenti di Security Copilot)

Note

Il ruolo di Proprietario della sottoscrizione è necessario per un'operazione di onboarding del data lake una tantum. Usare Microsoft Entra Privileged Identity Management (PIM) per elevare temporaneamente questo ruolo solo quando necessario, quindi rimuovere l'accesso al termine dell'onboarding.

Strumenti necessari

Visual Studio Code.
estensione di Microsoft Sentinel per VS Code
L'estensione GitHub Copilot VS Code è consigliata per velocizzare la creazione dei notebook.
Python 3.10+ installato in locale. Il kernel Spark viene eseguito in Azure, ma VS Code richiede un interprete locale per la modifica delle celle.

Panoramica processo

Il processo di pubblicazione inizia con lo sviluppo di notebook in locale, per poi passare a un'offerta SaaS pacchettizzata reperibile nel Microsoft Security Store.

Sviluppo di notebook locali (estensione VS Code + Sentinel)
Eseguire in modo interattivo sulla piattaforma Sentinel
Eseguire il test con dati rappresentativi; convalidare che la tabella di output venga popolata
Pianifica come job (su richiesta o pianificato)
Pacchetto come SentinelLake .zip (PackageManifest.yaml + cartella)
Creare un'offerta SaaS in Microsoft Partner Center
Caricare un pacchetto, creare metadati, piano e prezzi
Revisione e pubblicazione, revisione automatizzata, Go Live
In diretta su Microsoft Security Store

Installare Visual Studio Code e l'estensione Microsoft Sentinel

Tutto lo sviluppo di notebook avviene in locale in VS Code con l'estensione Microsoft Sentinel installata. Il kernel Spark viene eseguito in Azure: VS Code è l'editor e il client di invio.

Scaricare Visual Studio Code da https://code.visualstudio.com/ e installare con le opzioni predefinite.
Aprire il marketplace > di VS Code (CTRL+MAIUSC+X o CMD+MAIUSC+X).
Cercare Sentinel e installare l'estensione Microsoft Sentinel (publisher: ms-security).

Dopo l'installazione, l'icona Microsoft Sentinel viene visualizzata nella barra degli strumenti a sinistra.
(Scelta consigliata) Cercare GitHub Copilot nel marketplace, installarlo e accedere a GitHub quando richiesto.

Copilot conosce l'API MicrosoftSentinelProvider e completa automaticamente le trasformazioni PySpark.
Selezionare l'icona Microsoft Sentinel nella barra degli strumenti a sinistra.
Conferma la finestra di dialogo di accesso, quindi seleziona l'account con il ruolo Lettore/Collaboratore di Sentinel per l'area di lavoro.

Il riquadro a sinistra mostra tabelle Lake e Processi, confermando che l'estensione ha raggiunto il data lake.

Attenzione

Se hai effettuato l'accesso a più tenant guest, il cambio di account nell'angolo inferiore sinistro di VS Code interrompe qualsiasi sessione PySpark attiva: dopo aver cambiato account, devi riavviare il kernel. Pianifica i cambi di account tra un'esecuzione e l'altra, non durante un'esecuzione.

Crea il tuo notebook

I notebook usano questo modello di creazione:

Leggi una tabella data lake in un DataFrame Spark
Trasforma con PySpark
Facoltativamente, arricchire con dati esterni
Scrivere risultati in una tabella personalizzata che Sentinel può utilizzare

Esplora il pannello delle tabelle Lake

Per identificare le tabelle di input usate dal notebook, esplorare il pannello Tabelle Lake:

Selezionare l'icona Sentinel ed espandere tabelle Lake.
Le tabelle sono raggruppate per database e categoria (System, Custom, Federated). Selezionare qualsiasi tabella per visualizzare le relative definizioni e tipi di colonna.
Identificare le tabelle di input lette dal notebook e prendere nota dei nomi esatti.

Creare un nuovo notebook

Per creare un nuovo notebook di Jupyter per la soluzione, seguire questa procedura:

Premere Ctrl+Shift+P / Cmd+Shift+P>, quindi digitare Crea nuovo Jupyter Notebook, oppure selezionare File>Nuovo file>Jupyter Notebook.
Salvare il notebook con un nome descrittivo, ad esempio failed-signin-baseline.ipynb.

Leggere una tabella

Incollare questo modello nella prima cella e sostituire il nome della tabella con i valori seguenti:

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)

Selezionare un pool di runtime ed eseguire la cella

Per eseguire la cella sul data lake, selezionare un pool e inviare:

Selezionare il triangolo Run sulla cella.
Quando richiesto, scegliere Microsoft Sentinel come runtime.
Scegliere una dimensione del pool: piccola per l'esplorazione, Media per le trasformazioni, Grande per ML o aggregazioni su decine di milioni di righe.

La prima esecuzione richiede da 3 a 5 minuti per inizializzare la sessione Spark. Le celle successive vengono eseguite in pochi secondi.

Trasformare e scrivere nuovamente in una tabella personalizzata

Il save_as_table() metodo scrive un dataframe in una tabella personalizzata nel livello lake (o livello di analisi). La tabella di destinazione viene creata alla prima scrittura.

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,
)

Modelli di creazione di notebook

I modelli seguenti illustrano gli scenari più comuni:

Modello	Quando usarlo
Linea di base e deriva	Calcolare il comportamento normale per utente o per host; contrassegnare le righe che si discostano dal valore di riferimento. Classic per gli accessi non riusciti e l'analisi dell'esecuzione dei processi.
Join tra tabelle	Unisci la tabella del data lake di tua proprietà con le tabelle integrate (SigninLogs, SecurityAlert, DeviceProcessEvents) sulle entità condivise (UPN, host, IP).
Attribuzione del punteggio ML	Addestrare o caricare un modello preaddestrato nel notebook; assegnare un punteggio a ogni riga; scrivere le prime N righe più rischiose in una tabella di output personalizzata per la generazione di avvisi nei processi downstream.
Analisi visiva	Tracciare sequenze temporali, heatmap e alberi di elaborazione con matplotlib o plotly; esportare il notebook come HTML per la distribuzione.

Tip

Usa liberamente le celle Markdown per documentare il codice. Un revisore di Security Store — e l'analista SOC che gestisce il tuo notebook — devono capire cosa fa ogni sezione senza leggere il codice. Posizionare una cella markdown sopra ogni blocco di codice che spiega lo scopo, gli input, gli output e l'output previsto. I revisori considerano i notebook poco chiari motivo di bocciatura automatica.

Testare il notebook

Il test richiede di dimostrare che il notebook viene eseguito end-to-end su dati realistici e produce una tabella di output utilizzabile.

Test di fumo in piscina piccola

Esegui il notebook dall'inizio alla fine per verificare che ogni cella venga eseguita senza errori:

Riavviare il kernel per cancellare qualsiasi stato non aggiornato.
Eseguire tutte le celle dall'alto verso il basso. Ogni cella deve essere completata senza errori.

Se una cella di trasformazione richiede più di 5 minuti su Small, i filtri di input sono troppo sciolti. Riduci la proiezione della data o della colonna prima di passare a una scala superiore.

Convalidare la tabella di output

Verificare che la tabella di output sia stata creata e contenga i dati previsti:

Nel pannello Tabelle Lake dell'estensione Sentinel, aggiorna e verifica che la tabella di output appaia con lo schema previsto.
Eseguire una cella di verifica:

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

Test di scalabilità in pool medio o grande

Verificare che il notebook produa risultati coerenti con dimensioni maggiori del pool:

Esegui nuovamente il notebook in Medio (e in Grande se le dimensioni del set di dati lo richiedono).
Verificare che il numero di righe e le distribuzioni delle colonne corrispondano all'esecuzione ridotta. In caso di divergenza, si ha una trasformazione non deterministica che richiede un'analisi.

Test dei casi limite

Input vuoto: fa riferimento a una tabella o a un intervallo di date con zero righe. Il notebook dovrebbe gestire correttamente l'errore oppure scrivere un output vuoto, non arrestarsi.
Spostamento schema: se la tabella di input acquisisce una colonna, il notebook deve comunque poter essere eseguito. Non presupporre mai l'ordine posizionale.

Pianificare il notebook come processo

La maggior parte delle soluzioni notebook pubblicate viene eseguita in base a una pianificazione, ovvero una previsione oraria, un'analisi delle anomalie giornaliera e così via. L'estensione Sentinel trasforma qualsiasi notebook salvato in un processo pianificato che viene eseguito automaticamente in un pool di Spark gestito.

Creare l'attività

Per convertire il notebook in un processo pianificato, completare la procedura seguente:

Aprire il notebook in VS Code.
Selezionare Crea processo di pianificazione nel notebook, quindi scegliere Usa notebook esistente quando richiesto.

Per altre informazioni, vedere Creare e gestire processi di Jupyter Notebook.

Configurare il processo

Per configurare il processo pianificato, compilare i campi seguenti:

Immettere un nome del processo del kebab case che descriva il notebook (ad esempio, failed-signin-baseline-hourly).
Inserisci una Description composta da una sola frase che descriva lo scopo e la tabella di output.
Selezionare le dimensioni del pool di Spark convalidate durante i test. Non sovradimensionare: i processi vengono eseguiti su questo pool a ogni invocazione.
Per la Pianificazione, scegli Su richiesta per le esecuzioni manuali oppure Pianificato con una frequenza di ripetizione (a minuti, oraria, giornaliera, settimanale o mensile).
Selezionare Invia per pubblicare l'attività.

Verifica l'attività

Dopo l'invio, verificare che il processo sia in esecuzione correttamente:

Passa al pannello Jobs nell'estensione Sentinel: il tuo job dovrebbe essere visualizzato.
Selezionare il processo >Esegui ora per un'esecuzione di convalida immediata.
Al termine dell'esecuzione, passare alla scheda Cronologia di esecuzione per esaminare i log e l'intervallo.

Importante

I processi inviati sono scollegati dal tuo file .ipynb locale. La modifica del file locale non aggiorna il processo in esecuzione. Per aggiornare un processo: aprirlo nel riquadro Processi>Scaricare il notebook> modificare >Modifica processo>Invia per caricare la versione aggiornata.

Visualizza il processo nel portale Defender

Accedere a Microsoft Sentinel>Esplorazione dei data lake>Processi. È possibile abilitare o disabilitare la pianificazione e visualizzare la cronologia di esecuzione qui, ma non è possibile modificare il notebook dal portale.

Creare un pacchetto della soluzione notebook e pubblicarla

Dopo aver testato e materializzato il notebook, crea un pacchetto per distribuirlo ai clienti. Per istruzioni dettagliate sulla creazione e pubblicazione dei pacchetti, vedere Creazione e pubblicazione delle soluzioni Microsoft Sentinel per grafici e notebook.

Troubleshooting

Creazione di notebook

Sintomo	Probabile causa e correzione
`MicrosoftSentinelProvider` non trovato	Accesso all'estensione non effettuato oppure è stato aperto un kernel non Spark. Accedere all'estensione Microsoft Sentinel e selezionare il runtime Microsoft Sentinel quando richiesto.
La cella si blocca ad "Avvio della sessione Spark"	L'avvio della prima cella richiede da 3 a 5 minuti. Dopo 6 minuti, controlla l'indicatore di utilizzo dei vCore nella barra di stato: il pool potrebbe aver raggiunto la capacità massima. Provare una dimensione del pool più piccola.
`save_as_table` ha esito negativo con l'autorizzazione negata nel livello di analisi	L'identità gestita dal data lake `msg-resources-<guid>` non dispone del ruolo Collaboratore di Log Analytics nell'area di lavoro Log Analytics. Assegnarlo in base ai prerequisiti e riprovare.
La tabella di output viene visualizzata nel pannello Tabelle Lake , ma è vuota	Un `.filter()` probabilmente ha rimosso tutte le righe. Aggiungere una stampa del conteggio delle righe immediatamente prima di `save_as_table` per individuare il problema.

Per altre informazioni, vedere Risoluzione dei problemi dei notebook.

Programmazione dei processi

Sintomo	Probabile causa e correzione
Modifiche locali a `.ipynb` non riportate nell'attività pianificata	I processi inviati sono scollegati dal tuo fileluogo in cui ha sede la società locale. Scarica il processo da VS Code, modificalo, quindi usa Modifica processo>Invia per caricare la nuova versione.
L'attività viene eseguita ma non produce alcun output	Controlla la scheda Cronologia delle esecuzioni nel pannello Processi: il log di esecuzione di solito mostra la cella che causa l'errore. La causa più comune è la lettura del notebook da una tabella a cui l'identità in esecuzione non ha accesso.