Entwickeln einer Notizbuchlösung für Microsoft Sentinel

Als ISV-Partner können Sie Jupyter-Notizbuchanalyselösungen im Microsoft Security Store als SaaS-Angebote erstellen, testen, verpacken und veröffentlichen. Der Microsoft Sentinel-Data Lake unterstützt Jupyter Notebooks, die in verwalteten Spark-Pools für große Sicherheitsdatasets ausgeführt werden. Diese Notizbücher eignen sich ideal für die Erkennung von geringen und langsamen Angriffen, verhaltensbasierte Baselining, AI/ML-basierte Analysen, Zuordnung vertraulicher Datenpfade, Datenvisualisierungen und Anreicherungen, die herkömmliche KQL-Erkennungen nicht ausdrücken können.

Eine Notebook-Plattformlösung ist typischerweise für historische Analysen, komplexe Datentransformationen und wiederkehrende Datenverarbeitungs-Workflows konzipiert. Sie schreibt die Ausgabe in eine benutzerdefinierte Tabelle im Data Lake, in der nachgeschaltete Analyseregeln, Hunting-Abfragen, Security Copilot-Agents oder MCP-Tools die Ergebnisse der Notebooklösung nutzen können. Das .zip Paket, das Sie an Partner Center übermitteln, wird als Typ SentinelLake deklariert und enthält die Notizbücher und optional eine ARM-Vorlage für nachgeschaltete Azure Ressourcen, die das Notizbuch benötigt.

Dieser Artikel führt Sie durch den Bau, Testen, Packen und Veröffentlichen einer Microsoft Sentinel-Plattformnotebook-Lösung im Microsoft Security Store. Nachdem Sie diesen Leitfaden abgeschlossen haben, haben Sie Folgendes:

Ein funktionierendes Jupyter-Notizbuch, das Daten aus dem Sentinel-Datensee liest
Ein geplanter Auftrag, der das Notizbuch in einem verwalteten Spark-Pool ausführt
Ein SentinelLake ZIP-Paket (PackageManifest + Notebook-Ordner)
Ein Partner Center SaaS-Angebotseintrag im Microsoft Security Store

Voraussetzungen

Ihr Mandant muss in den Microsoft Sentinel-Data Lake integriert sein. Überprüfen Sie ihren Onboardingstatus im Defender-Portal. Navigieren Sie zu Systemeinstellungen>>Microsoft Sentinel>Datensee. Der Status lautet Bereitgestellt, wenn Ihr Mandant bereit ist. Anweisungen zum Onboarding finden Sie unter Onboarding zum Microsoft Sentinel Data Lake.

Erforderliche Berechtigungen

Vorgang/Ressource	Erforderliche Rolle
An Bord zum Sentinel-Datensee	Microsoft Entra ID – Sicherheitsadministrator oder globaler Administrator
Sentinel-Arbeitsbereich im Defender-Portal integrieren	Abonnementbesitzer oder Benutzerzugriffsadministrator im Abonnementbereich und Microsoft Sentinel-Mitwirkender auf Abonnement- oder Ressourcengruppenebene
Sentinel-Arbeitsbereich in Data Lake integrieren	Abonnementbesitzer oder Microsoft Sentinel-Mitwirkender auf Abonnement- oder Ressourcengruppenebene
Notebooks in einem Data Lake ausführen	Microsoft Sentinel Leser oder Mitwirkender
Log Analytics-Arbeitsbereich (für das Rückschreiben auf die Analytics-Ebene)	Log Analytics-Mitwirkender, der der verwalteten Data Lake-Identität `msg-resources-<guid>` zugewiesen ist
Microsoft Partner Center	Marketplace Publisher-Konto (einmal; dasselbe Konto, das für Security Copilot Agent Publishing verwendet wird)

Note

Die Rolle „Besitzer des Abonnements“ ist für eine einmalige Aufgabe zur Einbindung des Data Lake erforderlich. Verwenden Sie Microsoft Entra Privileged Identity Management (PIM), um diese Rolle nur bei Bedarf vorübergehend zu erhöhen, und entfernen Sie dann den Zugriff nach Abschluss des Onboardings.

Notwendige Werkzeuge

Visual Studio Code.
Microsoft Sentinel-Erweiterung für VS Code
Die GitHub Copilot VS Code-Erweiterung wird empfohlen, um das Erstellen von Notebooks zu beschleunigen.
Python 3.10+ lokal installiert. Der Spark-Kernel wird in Azure ausgeführt, aber VS Code benötigt einen lokalen Interpreter für die Zellbearbeitung.

Prozessüberblick

Der Veröffentlichungsprozess beginnt mit der lokalen Entwicklung von Notebooks und führt zu einem als Paket bereitgestellten SaaS-Angebot, das im Microsoft Security Store zu finden ist.

Lokale Notizbuchentwicklung (VS Code + Sentinel-Erweiterung)
Interaktives Ausführen für die Sentinel-Plattform
Testen mit repräsentativen Daten; Überprüfen, ob die Ausgabetabelle aufgefüllt wird
Als Auftrag planen (bedarfsgesteuert oder geplant)
Als SentinelLake-.zip paketieren (PackageManifest.yaml + Ordner)
SaaS-Angebot in Microsoft Partner Center erstellen
Hochladen von Paketen, Erstellen von Metadaten, Plan und Preisen
Überprüfen und Veröffentlichen, automatisierte Überprüfung, Go Live
Live im Microsoft Security Store

Installieren von Visual Studio Code und der Microsoft Sentinel-Erweiterung

Alle Notizbuchentwicklung erfolgt lokal in VS Code, wobei die Microsoft Sentinel Erweiterung installiert ist. Der Spark-Kernel wird in Azure ausgeführt– VS Code ist der Editor und der Übermittlungsclient.

Laden Sie Visual Studio Code von https://code.visualstudio.com/ herunter und installieren Sie es mit den Standardoptionen.
Öffnen Sie den VS Code->Erweiterungsmarktplatz (Ctrl+Shift+X oder Cmd+Shift+X).
Suchen Sie nach Sentinel, und installieren Sie die Microsoft Sentinel-Erweiterung (Herausgeber: ms-security).

Nach der Installation wird das symbol Microsoft Sentinel auf der linken Symbolleiste angezeigt.
(Empfohlen) Suchen Sie auf dem Marketplace nach GitHub Copilot, installieren Sie sie, und melden Sie sich bei GitHub an, wenn Sie dazu aufgefordert werden.

Copilot kennt die MicrosoftSentinelProvider API und vervollständigt PySpark-Transformationen automatisch.
Wählen Sie auf der linken Symbolleiste das symbol Microsoft Sentinel aus.
Bestätigen Sie den Anmeldedialog, und wählen Sie dann das Konto mit Sentinel Reader / Contributor für Ihren Arbeitsbereich aus.

Der linke Bereich zeigt Lake-Tabellen und Jobs an, was bestätigt, dass die Erweiterung den Data Lake erreicht hat.

Caution

Wenn Sie mehrere Gastmandanten angemeldet haben, beendet das Wechseln von Konten unten links von VS Code alle aktiven PySpark-Sitzungen – Sie müssen den Kernel nach dem Wechsel neu starten. Planen Sie Kontowechsel zwischen den Ausführungen, nicht währenddessen.

Entwickeln Sie Ihr Notebook

Notizbücher verwenden dieses Erstellungsmuster:

Einlesen einer Data-Lake-Tabelle in einen Spark-DataFrame
Transformieren mit PySpark
Optional mit externen Daten anreichern
Schreiben von Ergebnissen in eine benutzerdefinierte Tabelle, die Sentinel nutzen kann

Erkunden Sie den Bereich „Lake-Tabellen“

Um die von Ihrem Notizbuch verwendeten Eingabetabellen zu identifizieren, erkunden Sie den Tabellenbereich "Lake":

Wählen Sie das Sentinel-Symbol aus, und erweitern Sie Lake-Tabellen.
Tabellen werden nach Datenbank und Kategorie gruppiert (System, Benutzerdefiniert, Verbund). Wählen Sie eine beliebige Tabelle aus, um die zugehörigen Spaltendefinitionen und -typen anzuzeigen.
Identifizieren Sie die Eingabetabellen, die Ihr Notizbuch liest, und notieren Sie die genauen Namen.

Erstellen eines neuen Notebooks

Führen Sie die folgenden Schritte aus, um ein neues Jupyter-Notizbuch für Ihre Lösung zu erstellen:

Drücken Sie STRG+UMSCHALT+P / CMD+UMSCHALT+P>, geben Sie Neues Jupyter-Notebook erstellen ein, oder wählen Sie Datei>Neue Datei>Jupyter Notebook.
Speichern Sie das Notizbuch mit einem beschreibenden Namen (z. B failed-signin-baseline.ipynb. ).

Lesen einer Tabelle

Fügen Sie diese Vorlage in die erste Zelle ein, und ersetzen Sie den Tabellennamen durch Ihre:

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)

Wählen Sie einen Laufzeitpool aus, und führen Sie die Zelle aus.

Um die Zelle für den Data Lake auszuführen, wählen Sie einen Pool aus, und übermitteln Sie sie:

Wählen Sie auf der Zelle das „Ausführen“-Dreieck aus.
Wenn Sie dazu aufgefordert werden, wählen Sie Microsoft Sentinel als Laufzeit aus.
Wählen Sie eine Poolgröße aus: Klein für Die Erkundung, Mittel für Transformationen, Groß für ML oder Aggregationen über zehn Millionen Zeilen.

Die erste Ausführung dauert 3 bis 5 Minuten, um die Spark-Sitzung zu starten. Nachfolgende Zellen werden in Sekunden ausgeführt.

Transformieren und Zurückschreiben in eine benutzerdefinierte Tabelle

Die Methode save_as_table() schreibt einen DataFrame in eine benutzerdefinierte Tabelle auf der Lake-Ebene (oder Analyseebene). Die Zieltabelle wird beim ersten Schreiben erstellt.

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

Muster für die Notebook-Erstellung

Die folgenden Muster decken die am häufigsten verwendeten Szenarien ab:

Muster	Wann wird es verwendet?
Baseline + Drift	Normales Verhalten pro Benutzer oder pro Host ermitteln; Zeilen kennzeichnen, die von der Basislinie abweichen. Klassiker für Analysen zu fehlgeschlagenen Anmeldungen und Prozessausführungen.
Tabellenübergreifender Join	Verknüpfen Sie Ihre eigene Lake-Tabelle mit integrierten Tabellen (SigninLogs, SecurityAlert, DeviceProcessEvents) über freigegebene Entitäten (UPN, Host, IP).
ML-Bewertung	Trainieren oder laden Sie ein vortrainiertes Modell im Notebook, bewerten Sie jede Zeile, und schreiben Sie die N riskantesten Zeilen in eine benutzerdefinierte Ausgabetabelle für nachgeschaltete Warnungen.
Visuelle Untersuchung	Plotte Zeitlinien, Heatmaps und Prozessbäume mit Matplotlib oder Plotly; Exportiere das Notizbuch als HTML zur Übergabe.

Tip

Verwenden Sie Markdownzellen liberal, um Ihren Code zu dokumentieren. Ein Security Store-Prüfer – und der SOC-Analyst, der Ihr Notebook ausführt – muss verstehen, was die einzelnen Abschnitte tun, ohne den Code zu lesen. Platzieren Sie eine Markdownzelle über jedem Codeblock, der Zweck, Eingaben, Ausgaben und erwartete Ausgabe erklärt. Prüfer behandeln unklare Notizbücher als hartes Fehlschlagen.

Testen des Notizbuchs

Tests erfordern den Nachweis, dass das Notebook auf realistischen Daten durchgängig läuft und eine nutzbare Ausgabetabelle erzeugt.

Smoke-Test im Small Pool

Führen Sie das Notebook durchgängig aus, um zu bestätigen, dass jede Zelle fehlerfrei abgeschlossen wird:

Starten Sie den Kernel neu, um den veralteten Zustand zu löschen.
Führen Sie alle Zellen von oben nach unten aus – jede Zelle muss ohne Fehler abgeschlossen werden.

Wenn eine Transformationszelle auf „Small“ länger als 5 Minuten dauert, sind Ihre Eingabefilter zu locker. Festigen Sie die Datums- oder Spaltenprojektion vor der Skalierung.

Überprüfen Sie die Ausgabetabelle

Vergewissern Sie sich, dass die Ausgabetabelle erstellt wurde und die erwarteten Daten enthält:

Aktualisieren Sie im Bereich Lake-Tabellen der Sentinel-Erweiterung, und bestätigen Sie, dass Ihre Ausgabetabelle mit dem erwarteten Schema angezeigt wird.
Führen Sie eine Überprüfungszelle aus:

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

Skalierungstest auf mittlerem oder großem Pool

Überprüfen Sie, ob das Notizbuch konsistente Ergebnisse für größere Poolgrößen erzeugt:

Führen Sie das Notebook erneut auf „Medium“ (und „Large“, wenn Ihr Dataset dies rechtfertigt) aus.
Bestätigen Sie, dass die Zeilenanzahl und die Spaltenverteilungen mit dem kleinen Durchlauf übereinstimmen. Wenn sie voneinander abweichen, verfügen Sie über eine nicht deterministische Transformation, die eine Untersuchung erfordert.

Test von Randfällen

Leere Eingabe: Zeigen Sie auf eine Tabelle oder einen Datumsbereich mit null Zeilen. Das Notebook sollte ordnungsgemäß fehlschlagen oder eine leere Ausgabe schreiben – nicht abstürzen.
Schemaabweichung: Wenn Ihre Eingabetabelle eine Spalte erhält, sollte das Notebook weiterhin ausgeführt werden. Gehen Sie niemals von einer festen Reihenfolge aus.

Planen des Notebooks als Auftrag

Die meisten veröffentlichten Notebook-Lösungen laufen nach einem Zeitplan – stündlicher Basislauf, tägliche Anomalieprüfung usw. Die Sentinel-Erweiterung wandelt jedes gespeicherte Notizbuch in einen geplanten Auftrag um, der auf einem verwalteten Spark-Pool unbeaufsichtigt ausgeführt wird.

Auftrag erstellen

Führen Sie die folgenden Schritte aus, um das Notizbuch in einen geplanten Auftrag zu konvertieren:

Öffnen Sie Ihr Notizbuch in VS Code.
Wählen Sie im Notizbuch " Zeitplanauftrag erstellen " aus, und wählen Sie dann " Vorhandenes Notizbuch verwenden " aus, wenn Sie dazu aufgefordert werden.

Weitere Informationen finden Sie unter Erstellen und Verwalten von Jupyter-Notizbuchaufträgen.

Auftrag konfigurieren

Um den geplanten Auftrag zu konfigurieren, füllen Sie die folgenden Felder aus:

Geben Sie einen Auftragsnamen in Kebab-Case-Schreibweise ein, der das Notebook beschreibt (z. B. failed-signin-baseline-hourly).
Geben Sie eine aus einem Satz bestehende Beschreibung ein, die den Zweck und die Ausgabetabelle des Auftrags beschreibt.
Wählen Sie die Spark-Poolgröße aus, die Sie während des Tests überprüft haben. Wählen Sie keine zu große Dimensionierung – Aufträge werden bei jedem Aufruf in diesem Pool ausgeführt.
Wählen Sie für den Zeitplan die Option "Bei Bedarf für manuelle Ausführungen" oder " Geplant " mit einer Wiederholungshäufigkeit (Minute, Stündlich, täglich, wöchentlich oder monatlich) aus.
Wählen Sie "Absenden" aus, um den Auftrag zu veröffentlichen.

Aufgabe überprüfen

Vergewissern Sie sich nach der Übermittlung, dass der Auftrag ordnungsgemäß ausgeführt wird:

Wechseln Sie in der Sentinel-Erweiterung zum Bereich "Aufträge ". Ihr Auftrag sollte angezeigt werden.
Wählen Sie den Auftrag >"Jetzt ausführen " aus, um eine sofortige Überprüfung auszuführen.
Wechseln Sie nach Abschluss der Ausführung zur Registerkarte Ausführungsverlauf, um Protokolle und Laufzeiten einzusehen.

Important

Übermittelte Aufträge werden von Ihrer lokalen .ipynb Datei entkoppelt. Durch das Bearbeiten der lokalen Datei wird der ausgeführte Auftrag nicht aktualisiert. Um einen Job zu aktualisieren: Öffnen Sie ihn im Bereich Jobs>Laden Sie das Notebook herunter>, bearbeiten Sie >Job bearbeiten>Absenden, um die aktualisierte Version hochzuladen.

Auftrag im Defender-Portal anzeigen

Navigieren Sie zu Microsoft Sentinel>Data Lake-Explorer>Aufträge. Sie können den Zeitplan und den Ausführungsverlauf hier aktivieren oder deaktivieren, aber das Notizbuch nicht über das Portal bearbeiten.

Packen und veröffentlichen Sie Ihre Notebook-Lösung

Nachdem Ihr Notizbuch getestet und materialisiert wurde, packen Sie es für die Bereitstellung für Kunden. Ausführliche Anweisungen zum Packen finden Sie unter Microsoft Sentinel Graph- und Notebooklösungen packen und veröffentlichen.

Problembehandlung

Notizbucherstellung

Symptom	Wahrscheinliche Ursache und Behebung
`MicrosoftSentinelProvider` nicht gefunden	Die Erweiterung ist nicht angemeldet, oder Sie haben einen Nicht-Spark-Kernel geöffnet. Melden Sie sich bei der Microsoft Sentinel-Erweiterung an, und wählen Sie die Microsoft Sentinel Laufzeit aus, wenn Sie dazu aufgefordert werden.
Zelle sitzt fest bei „Startet Spark-Sitzung”	Der Start der ersten Zelle dauert 3 bis 5 Minuten. Überprüfen Sie nach 6 Minuten den vCore-Auslastungsindikator in der Statusleiste – Ihr Pool ist möglicherweise ausgelastet. Versuchen Sie es mit einer kleineren Poolgröße.
`save_as_table` schlägt mit „Zugriff verweigert“ in der Analyseebene fehl	Die verwaltete Identität `msg-resources-<guid>` des Data Lake verfügt nicht über die Rolle „Log Analytics-Mitwirkender“ für den Log Analytics-Arbeitsbereich. Weisen Sie es gemäß den Voraussetzungen zu und versuchen Sie es erneut.
Die Ausgabetabelle wird im Tabellenbereich "Lake" angezeigt, ist aber leer.	`.filter()` hat wahrscheinlich alle Zeilen entfernt. Fügen Sie unmittelbar vor `save_as_table` eine Zeilenanzahlausgabe hinzu, um das Problem zu lokalisieren.

Weitere Informationen finden Sie unter "Problembehandlung bei Notizbüchern".

Feinterminierung

Symptom	Wahrscheinliche Ursache und Behebung
Änderungen an der lokalen `.ipynb`-Datei werden im geplanten Auftrag nicht widergespiegelt	Übermittelte Aufträge werden von der lokalen Datei entkoppelt. Laden Sie den Job aus VS Code herunter, bearbeiten Sie ihn und verwenden Sie dann Job bearbeiten>Senden, um die neue Version hochzuladen.
Auftrag wird ausgeführt, erzeugt aber keine Ausgabe	Überprüfen Sie die Registerkarte " Verlauf ausführen " im Bereich "Aufträge ". Das Ausführungsprotokoll zeigt in der Regel die fehlerhafte Zelle an. Die häufigste Ursache ist, dass das Notebook aus einer Tabelle liest, auf die die ausführende Identität keinen Zugriff hat.