Utveckla en notebook-lösning för Microsoft Sentinel

Som ISV-partner kan du skapa, testa, paketera och publicera Jupyter Notebook Analytics-lösningar till Microsoft Security Store som SaaS erbjuder. Microsoft Sentinel-datasjön har stöd för Jupyter-anteckningsböcker som körs i hanterade Spark-pooler på stora säkerhetsdatamängder. Dessa notebooks är väl lämpade för detektering av lågintensiva, långsamma attacker, etablering av beteendebaslinjer, AI/ML-baserade analyser, kartläggning av flöden för känsliga data, datavisualiseringar och berikningar som traditionella KQL-detekteringar inte kan fånga.

En notebook-plattform är vanligtvis utformad för historisk analys, komplexa datatransformationer och återkommande databehandlingsarbetsflöden. Den skriver utdata till en anpassad tabell i datalaken, där nedströms analytiska regler, jaktfrågor, Security Copilot-agenter eller MCP-verktyg kan konsumera resultaten från notebook-lösningen. Paketet .zip som du skickar till Partner Center deklareras som typen SentinelLake och innehåller notebook-filerna och eventuellt en ARM-mall för de ytterligare Azure-resurser som notebook-filerna behöver.

Den här artikeln guidar dig genom att bygga, testa, paketera och publicera en Microsoft Sentinel-plattform för bärbar dator till Microsoft Security Store. När du har slutfört den här guiden har du:

En fungerande Jupyter-anteckningsbok som läser data från Sentinel-datasjön
Ett schemalagt jobb som kör notebook-filen i en hanterad Spark-pool
Ett SentinelLake zip-paket (PackageManifest + anteckningsboksmapp)
En SaaS-erbjudandelista för Partnercenter i Microsoft Security Store

Förutsättningar

Din klientorganisation måste ha registrerats för Microsoft Sentinel-datasjön. Kontrollera registreringsstatusen i Defender-portalen. Gå till Systeminställningar>>Microsoft Sentinel>Data lake. Statusen visar Provisionerad om din klientorganisation är redo. Anvisningar för registrering finns i Registrera i Microsoft Sentinel-datasjön.

Behörigheter som krävs

Åtgärd/resurs	Obligatorisk roll
Ombord till Sentinel-datasjön	Microsoft Entra ID – säkerhetsadministratör eller global administratör
Anslut Sentinel-arbetsytan till Defender-portalen	Ägare av prenumeration eller administratör för användaråtkomst på prenumerationsnivå och Microsoft Sentinel-deltagare på prenumerations- eller resursgruppsnivå
Anslut Sentinel-arbetsytan till Data Lake	Prenumerationsägare eller Microsoft Sentinel-deltagare på prenumerations- eller resursgruppsnivå
Köra notebook-filer på datasjön	Microsoft Sentinel-läsare eller medverkande
Log Analytics arbetsyta (för tillbakaskrivning till analysnivå)	Log Analytics-deltagare tilldelad till den data-lake-hanterade identiteten `msg-resources-<guid>`
Microsoft Partner Center	Marketplace Publisher-konto (engångskonto; samma konto som används för publicering av Security copilot-agenter)

Note

Rollen Prenumerationsägare krävs för en engångsuppgift för onboarding av en datasjö. Använd Microsoft Entra Privileged Identity Management (PIM) för att tillfälligt höja till den här rollen endast när det behövs och ta sedan bort åtkomsten när registreringen har slutförts.

Verktyg som krävs

Visual Studio Code.
Microsoft Sentinel VS Code-tillägg
GitHub Copilot VS Code-tillägget rekommenderas för att snabba upp skrivandet av anteckningsböcker.
Python 3.10+ installerat lokalt. Spark-kerneln körs i Azure men VS Code behöver en lokal tolk för cellredigering.

Översikt över processen

Publiceringsprocessen börjar med att lokal notebookutveckling övergår till ett paketerat SaaS-erbjudande som kan hittas i Microsoft Security Store.

Lokal notebookutveckling (VS Code + Sentinel-tillägg)
Kör interaktivt mot Sentinel-plattformen
Testa mot representativa datauppsättningar; verifiera att utdatatabellen fylls med data
Schemalägg som ett jobb (på begäran eller schemalagt)
Paketera som SentinelLake .zip (PackageManifest.yaml + mapp)
Skapa SaaS-erbjudande i Microsoft Partner Center
Ladda upp paket, skapa metadata, planera och priser
Granska och publicera, automatiserad granskning, Gå live
Direkt på Microsoft Security Store

Installera Visual Studio Code och Microsoft Sentinel-tillägget

All utveckling av notebook-filer sker lokalt i VS Code med Microsoft Sentinel-tillägget installerat. Spark-kerneln körs i Azure – VS Code är redigeraren och överföringsklienten.

Ladda ned Visual Studio Code från https://code.visualstudio.com/ och installera med standardalternativ.
Öppna VS Code >Extensions Marketplace (Ctrl+Skift+X eller Cmd+Skift+X).
Sök efter Sentinel och installera Microsoft Sentinel-tillägget (utgivare: ms-security).

Efter installationen visas ikonen Microsoft Sentinel i det vänstra verktygsfältet.
(Rekommenderas) Sök efter GitHub Copilot på marketplace, installera den och logga in på GitHub när du uppmanas att göra det.

Copilot känner till MicrosoftSentinelProvider API och kompletterar pyspark-transformeringar automatiskt.
Välj ikonen Microsoft Sentinel i det vänstra verktygsfältet.
Godkänn inloggningsdialogrutan och välj sedan kontot med Sentinel Reader/Contributor på din arbetsyta.

Den vänstra rutan visar Lake-tabeller och Jobb, vilket bekräftar att tillägget har nått datasjön.

Caution

Om du har flera gästklienter inloggade avslutas alla aktiva PySpark-sessioner när du byter konto längst ned till vänster i VS Code – du måste starta om kärnan efter bytet. Planera kontobyten mellan körningar, inte under körningarna.

Arbeta vidare med din notebook

Anteckningsböcker använder denna redigeringsmodell:

Läsa en datasjötabell i en Spark DataFrame
Transformera med PySpark
Du kan även utöka med externa data
Skriva resultat till en anpassad tabell som Sentinel kan använda

Utforska panelen för Lake-tabeller

Identifiera vilka indatatabeller din notebook använder genom att utforska panelen för Lake-tabeller:

Välj Sentinel-ikonen och expandera Lake-tabeller.
Tabeller grupperas efter databas och kategori (System, Anpassad, Federerad). Välj valfri tabell om du vill se dess kolumndefinitioner och typer.
Identifiera indatatabellerna som anteckningsboken läser och anteckna de exakta namnen.

Skapa en ny anteckningsbok

Utför följande steg för att skapa en ny Jupyter-anteckningsbok för din lösning:

Tryck på Ctrl+Skift+P / Cmd+Skift+P> skriv Skapa ny Jupyter Notebook eller välj Arkiv>Ny fil>Jupyter Notebook.
Spara anteckningsboken med ett beskrivande namn (till exempel failed-signin-baseline.ipynb).

Läs en tabell

Klistra in den här mallen i den första cellen och ersätt tabellnamnet med ditt:

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)

Välj en pool för körningsmiljöer och kör cellen

Om du vill köra cellen mot datasjön väljer du en pool och skickar:

Välj triangeln Kör i cellen.
När du uppmanas väljer du Microsoft Sentinel som körningsmiljö.
Välj en poolstorlek: Liten för utforskning, Medel för transformeringar, Stor för ML eller sammansättningar över tiotals miljoner rader.

Den första körningen tar 3–5 minuter för att starta upp Spark-sessionen. Följande celler körs på några sekunder.

Transformera och skriv tillbaka till en anpassad tabell

Metoden save_as_table() skriver en DataFrame till en anpassad tabell på sjönivån (eller analysnivån). Måltabellen skapas vid första skrivningen.

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

Mönster för redigering av notebook-filer

Följande mönster omfattar de vanligaste scenarierna:

Mönster	När du ska använda detta
Baslinje + drift	Beräkna normalt beteende per användare eller per värd; markera rader som avviker från baslinjen. Klassisk för analys av misslyckad inloggning och processkörning.
Sammanslagning mellan tabeller	Anslut laketabellen som du äger med inbyggda tabeller (SigninLogs, SecurityAlert, DeviceProcessEvents) på delade entiteter (UPN, värd, IP).
ML-poängsättning	Träna eller ladda en förtränad modell i anteckningsboken; poängsätt varje rad; skriv de N mest riskfyllda raderna till en anpassad utdatatabell för efterföljande aviseringar.
Visuell undersökning	Plotta tidslinjer, värmekartor och processträd med matplotlib eller plotly; exportera anteckningsboken som HTML för överlämning.

Tip

Använd markdown-celler liberalt för att dokumentera koden. En granskare av Security Store – och SOC-analytikern som kör din notebook – behöver förstå vad varje avsnitt gör utan att läsa koden. Placera en markdown-cell ovanför varje kodblock som förklarar syfte, indata, utdata och förväntade utdata. Granskare behandlar otydliga notebook-filer som ett svårt fel.

Testa anteckningsboken

Testning kräver att man visar att notebooken kan köras från början till slut med realistiska data och resulterar i en användbar resultattabell.

Smoketest på Small pool

Kör anteckningsboken från början till slut för att kontrollera att varje cell körs klart utan fel:

Starta om kärnan för att rensa eventuella inaktuella tillstånd.
Kör alla celler uppifrån och ned – varje cell måste slutföras utan fel.

Om en transformeringscell tar mer än 5 minuter på Small är dina indatafilter för lösa. Dra åt datum- eller kolumnprojektionen innan du skalar upp.

Verifiera utdatatabellen

Bekräfta att utdatatabellen skapades och innehåller förväntade data:

I panelen Lake-tabeller i Sentinel-tillägget uppdaterar och bekräftar du att utdatatabellen visas med det förväntade schemat.
Kör en verifieringscell:

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

Skalningstest på medelstor eller stor pool

Kontrollera att anteckningsboken producerar konsekventa resultat för större poolstorlekar:

Kör notebooken igen på Medium (och på Large om datauppsättningen kräver det).
Kontrollera att antal rader och kolumnfördelningar stämmer överens med Small-körningen. Om de skiljer sig åt har du en icke-deterministisk transformering som behöver undersökas.

Testa gränsfall

Tomma indata: Peka på en tabell eller ett datumintervall med noll rader. Anteckningsboken bör hantera felet på ett kontrollerat sätt eller skriva ut tomma utdata – inte krascha.
Schemaförändring: Om indatatabellen får en ny kolumn ska anteckningsboken fortfarande kunna köras. Anta aldrig positionell ordning.

Schemalägga anteckningsboken som ett jobb

De flesta publicerade notebook-lösningar körs enligt ett schema – timbaslinje, daglig avvikelsesökning och så vidare. Sentinel-tillägget omvandlar en sparad notebook-fil till ett schemalagt jobb som körs obevakat på en hanterad Spark-pool.

Skapa jobbet

Utför följande steg för att konvertera anteckningsboken till ett schemalagt jobb:

Öppna anteckningsboken i VS Code.
Välj Skapa schemajobb i anteckningsboken och välj sedan Använd befintlig anteckningsbok när du uppmanas till det.

Mer information finns i Skapa och hantera Jupyter Notebook-jobb.

Konfigurera jobbet

Om du vill konfigurera det schemalagda jobbet fyller du i följande fält:

Ange ett jobbnamn i kebabformat som beskriver anteckningsboken (till exempel failed-signin-baseline-hourly).
Ange en beskrivning med en mening som täcker jobbets syfte och utdatatabell.
Välj storleken på Spark-poolen som du verifierade under testningen. Överdimensionera inte – jobb körs på den här poolen vid varje anrop.
För Schema väljer du På begäran för manuella körningar eller Schemalagd med en upprepningsfrekvens (minut, timme, dag, vecka eller månad).
Välj Skicka för att publicera jobbet.

Verifiera jobbet

När du har skickat in det, bekräfta att jobbet körs korrekt:

Växla till panelen Jobb i Sentinel-tillägget – jobbet ska visas.
Välj jobbet >Kör nu för en omedelbar valideringskörning.
När körningen är klar växlar du till fliken Körningshistorik för att inspektera loggar och tidsinställningar.

Important

Skickade jobb är frikopplade från din lokala .ipynb fil. Redigering av den lokala filen uppdaterar inte det jobb som körs. Så här uppdaterar du ett jobb: öppna det i panelen >Ladda ned anteckningsboken>> Redigera jobb >Skicka för att ladda upp den uppdaterade versionen.

Visa jobbet i Defender-portalen

Gå till Microsoft Sentinel>Data lake exploration>Jobs. Du kan aktivera eller inaktivera schemat och visa körningshistoriken här, men det går inte att redigera anteckningsboken från portalen.

Paketera och publicera din notebook-lösning

När notebooken har testats och materialiserats paketerar du den för driftsättning hos kunder. Detaljerade paketeringsinstruktioner finns i Paketera och publicera Microsoft Sentinel graf- och notebook-lösningar.

Troubleshooting

Redigering av notebook-filer

Symptom	Sannolik orsak och korrigering
`MicrosoftSentinelProvider` hittades inte	Tillägget är inte loggat in eller så har du öppnat en icke-Spark-kernel. Logga in i tillägget Microsoft Sentinel och välj körmiljön Microsoft Sentinel när du uppmanas.
Cellen låser sig vid "Starta Spark-session"	Start av första cellen tar 3 till 5 minuter. Efter 6 minuter kontrollerar du indikatorn för användning av virtuella kärnor i statusfältet – din pool kan ha kapacitet. Prova en mindre poolstorlek.
`save_as_table` misslyckas på grund av nekad behörighet på analysnivån	Data-lake managed identity `msg-resources-<guid>` har inte Log Analytics Contributor på Log Analytics-arbetsytan. Tilldela den enligt förutsättningarna och försök igen.
Utdatatabellen visas i panelen Lake-tabeller men är tom	`.filter()` tog sannolikt bort alla rader. Lägg till en radräkningsutskrift omedelbart innan `save_as_table` för att lokalisera problemet.

Mer information finns i felsökning för Notebooks.

Finplanering

Symptom	Sannolik orsak och korrigering
Redigeringar till lokalt `.ipynb` återspeglas inte i schemalagt jobb	Skickade jobb frikopplas från den lokala filen. Ladda ned jobbet från VS Code, redigera det och använd sedan Redigera jobb>Skicka för att ladda upp den nya versionen.
Jobbet körs men genererar inga utdata	Kontrollera fliken Körningshistorik i panelen Jobb . Körningsloggen visar vanligtvis den cell som inte fungerar. Den vanligaste orsaken är att notebooken läser från en tabell som den identitet som används vid körning inte har åtkomst till.