Opracuj rozwiązanie oparte na notesie dla usługi Microsoft Sentinel

Jako partner ISV możesz tworzyć, testować, pakować i publikować w rozwiązania zabezpieczające firmy Microsoft Store rozwiązania analityczne oparte na notesach Jupyter jako oferty SaaS. Magazyn danych Microsoft Sentinel obsługuje notatniki Jupyter uruchamiane w zarządzanych pulach Spark na dużych zbiorach danych dotyczących zabezpieczeń. Te notesniki idealnie nadają się do wykrywania ataków prowadzonych powoli i skrycie, ustalania wzorców bazowych zachowań, analiz opartych na sztucznej inteligencji i uczeniu maszynowym, mapowania przepływu danych wrażliwych, wizualizacji danych oraz wzbogacania danych, których nie da się wyrazić za pomocą tradycyjnych detekcji KQL.

Rozwiązanie platformy notebooków jest zazwyczaj projektowane do analizy historycznej, złożonych transformacji danych oraz powtarzających się procesów przetwarzania danych. Zapisuje dane wyjściowe w niestandardowej tabeli w jeziorze danych, z której dalsze reguły analityczne, zapytania do wyszukiwania zagrożeń, agenci Security Copilot lub narzędzia MCP mogą wykorzystywać wyniki rozwiązania opartego na notesie. Pakiet .zip, który przesyłasz do Partner Center, jest zadeklarowany jako typ SentinelLake i zawiera notatniki oraz opcjonalnie szablon ARM dla zasobów platformy Azure, których wymaga notatnik.

Ten artykuł przeprowadzi Cię przez budowanie, testowanie, pakowanie i publikację rozwiązania platformowego notatnika Microsoft Sentinel w rozwiązania zabezpieczające firmy Microsoft Store. Po ukończeniu tego przewodnika będziesz mieć następujące elementy:

Działający notatnik Jupyter, który odczytuje dane z jeziora danych Sentinel
Zaplanowane zadanie uruchamiające notes w zarządzanej puli Spark
Pakiet zip SentinelLake (PackageManifest + folder notesów)
Oferta SaaS Centrum partnerskiego w sklepie rozwiązania zabezpieczające firmy Microsoft

Wymagania wstępne

Dzierżawa musi być dołączona do usługi Microsoft Sentinel data lake. Sprawdź stan wdrożenia w portalu Defender. Przejdź do System>Ustawienia>Microsoft Sentinel>Data lake. Status ma wartość Udostępniono, jeśli dzierżawca jest gotowy. Instrukcje dotyczące wdrażania znajdują się tutaj: Wdrażanie do jeziora danych w usłudze Microsoft Sentinel.

Wymagane uprawnienia

Operacja/Zasób	Wymagana rola
Dołącz do jeziora danych Sentinel	Microsoft Entra ID — administrator zabezpieczeń lub administrator globalny
Dołączanie obszaru roboczego usługi Sentinel do portalu Defender	Właściciel subskrypcji lub administrator dostępu użytkowników na poziomie subskrypcji oraz współautor Microsoft Sentinel na poziomie subskrypcji lub grupy zasobów
Dołącz obszar roboczy Microsoft Sentinel do Data Lake	Właściciel subskrypcji lub współautor usługi Microsoft Sentinel na poziomie subskrypcji lub grupy zasobów
Uruchamianie notatników w jeziorze danych	Microsoft Sentinel — Czytelnik lub Współautor
obszar roboczy usługi Log Analytics (do zapisu zwrotnego w warstwie analitycznej)	Współautor usługi Log Analytics przypisany do tożsamości zarządzanej data-lake `msg-resources-<guid>`
Centrum partnerskie firmy Microsoft	Konto wydawcy w Marketplace (jednorazowo; to samo konto używane do publikowania agentów Security Copilot)

Note

Rola Właściciela subskrypcji jest wymagana do jednorazowego zadania wdrożenia jeziora danych. Użyj Microsoft Entra Privileged Identity Management (PIM), aby tymczasowo przypisać sobie tę rolę tylko w razie potrzeby, a następnie usunąć dostęp po zakończeniu wdrożenia.

Wymagane narzędzia

Visual Studio Code.
rozszerzenie VS Code dla Microsoft Sentinel
Zalecane jest rozszerzenie GitHub Copilot VS Code, które przyspiesza tworzenie notebooków.
Python zainstalowany lokalnie w wersji 3.10 lub nowszej. Jądro Spark działa w Azure, ale program VS Code wymaga lokalnego interpretera do edycji komórek.

Przegląd procesu

Proces publikowania rozpoczyna się od lokalnego tworzenia notesników, a następnie przechodzi do spakietowanej oferty SaaS, którą można znaleźć w sklepie rozwiązania zabezpieczające firmy Microsoft Store.

Programowanie notesu lokalnego (rozszerzenie VS Code + Sentinel)
Uruchamianie interakcyjne na platformie Sentinel
Przetestuj dane reprezentatywne; sprawdzanie poprawności wypełnionej tabeli wyjściowej
Planowanie jako zadanie (na żądanie lub zaplanowane)
Spakuj jako plik .zip SentinelLake (PackageManifest.yaml + folder)
Tworzenie oferty SaaS w Microsoft Partner Center
Przekazywanie pakietu, tworzenie metadanych, planowanie i cennik
Przeglądanie i publikowanie, automatyczna recenzja, Go Live
Dostępne w Sklepie rozwiązania zabezpieczające firmy Microsoft

Instalowanie programu Visual Studio Code i rozszerzenia usługi Microsoft Sentinel

Wszystkie programowanie notesów odbywa się lokalnie w programie VS Code z zainstalowanym rozszerzeniem Microsoft Sentinel. Jądro Platformy Spark działa w Azure — program VS Code jest edytorem i klientem przesyłania.

Pobierz Visual Studio Code z https://code.visualstudio.com/ witryny i zainstaluj przy użyciu opcji domyślnych.
Otwórz > programu VS Code (Ctrl+Shift+X lub Cmd+Shift+X).
Wyszukaj usługę Sentinel i zainstaluj rozszerzenie Microsoft Sentinel (wydawca: ms-security).

Po zakończeniu instalacji ikona Microsoft Sentinel zostanie wyświetlona na lewym pasku narzędzi.
(Zalecane) Wyszukaj GitHub Copilot w Marketplace, zainstaluj go i po wyświetleniu monitu zaloguj się do GitHub.

Copilot zna interfejs MicrosoftSentinelProvider API i automatycznie uzupełnia transformacje PySpark.
Wybierz ikonę Microsoft Sentinel na lewym pasku narzędzi.
Zatwierdź okno dialogowe logowania, a następnie wybierz konto z czytelnikiem/współautorem usługi Sentinel w obszarze roboczym.

W okienku po lewej stronie są wyświetlane tabele lake i zadania, co potwierdza, że rozszerzenie dotarło do usługi Data Lake.

Caution

Jeśli jesteś zalogowany do wielu dzierżaw gościnnych, przełączenie konta w lewym dolnym rogu programu VS Code kończy wszystkie aktywne sesje PySpark — po przełączeniu musisz ponownie uruchomić kernel. Zaplanuj przełączanie kont między uruchomieniami, a nie w ich trakcie.

Twórz swój notatnik

Notatniki używają tego schematu tworzenia:

Wczytać tabelę z jeziora danych do ramki danych Spark
Przekształcanie za pomocą narzędzia PySpark
Opcjonalnie wzbogacaj danymi zewnętrznymi
Zapisz wyniki w tabeli niestandardowej, z której może korzystać Sentinel

Przeglądaj panel tabel Lake

Aby zidentyfikować tabele wejściowe, z których korzysta Twój notatnik, przejrzyj panel Tabele Lake:

Wybierz ikonę Sentinel i rozwiń tabele Lake.
Tabele są grupowane według bazy danych i kategorii (System, Niestandardowy, Federacyjny). Wybierz dowolną tabelę, aby wyświetlić jej definicje i typy kolumn.
Zidentyfikuj tabele wejściowe, które odczytuje notes, i zanotuj dokładne nazwy.

Utwórz nowy notatnik

Aby utworzyć nowy notes Jupyter dla swojego rozwiązania, wykonaj następujące kroki:

Naciśnij klawisze Ctrl+Shift+P / Cmd+Shift+P> wpisz Utwórz nowy Jupyter Notebook lub wybierz pozycję Plik>nowy>Jupyter Notebook.
Zapisz notes z opisową nazwą (na przykład failed-signin-baseline.ipynb).

Odczytywanie tabeli

Wklej ten szablon do pierwszej komórki i zastąp nazwę tabeli twoimi:

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)

Wybierz pulę środowiska uruchomieniowego i uruchom komórkę

Aby uruchomić komórkę w usłudze Data Lake, wybierz pulę i prześlij:

Wybierz trójkąt Uruchom w komórce.
Po wyświetleniu monitu wybierz Microsoft Sentinel jako środowisko uruchomieniowe.
Wybierz rozmiar puli: mały do eksploracji, Średni dla przekształceń, Duży dla uczenia maszynowego lub agregacji ponad dziesiątek milionów wierszy.

Pierwsze uruchomienie zajmuje od 3 do 5 minut, aby zainicjować sesję Spark. Kolejne komórki są uruchamiane w sekundach.

Przekształcić i zapisać z powrotem do tabeli niestandardowej

Metoda save_as_table() zapisuje obiekt DataFrame do niestandardowej tabeli w warstwie lake (lub warstwie analitycznej). Tabela docelowa jest tworzona przy pierwszym zapisie.

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

Wzorce tworzenia notatników

Poniższe wzorce obejmują najbardziej typowe scenariusze:

Wzór	Kiedy należy go używać
Poziom bazowy + dryf	Oblicz normalne zachowanie dla każdego użytkownika lub hosta; oznaczaj wiersze, które odbiegają od poziomu bazowego. Wersja klasyczna dla analizy nieudanego logowania i wykonywania procesów.
Łączenie tabel	Dołącz tabelę typu lake, której jesteś właścicielem, korzystając z wbudowanych tabel (SigninLogs, SecurityAlert, DeviceProcessEvents) w jednostkach udostępnionych (UPN, host, IP).
Ocenianie modeli uczenia maszynowego	Wytrenuj lub załaduj wstępnie wytrenowany model w notatniku; oceń każdy wiersz; zapisz N wierszy o najwyższym poziomie ryzyka w niestandardowej tabeli wyjściowej na potrzeby dalszego generowania alertów.
Badanie wizualne	Twórz wykresy osi czasu, mapy cieplne i drzewa procesów za pomocą matplotlib lub plotly; wyeksportuj notatnik jako plik HTML do przekazania.

Wskazówka

Często używaj komórek Markdown do dokumentowania kodu. Recenzent w Security Store — oraz analityk SOC, który uruchamia Twój notatnik — muszą rozumieć, do czego służy każda sekcja, bez zaglądania do kodu. Umieść komórkę markdown nad każdym blokiem kodu wyjaśniającym przeznaczenie, dane wejściowe, dane wyjściowe i oczekiwane dane wyjściowe. Recenzenci traktują niejasne notesy jako trudne niepowodzenie.

Przetestuj notebook

Testowanie wymaga udowodnienia, że notes działa kompleksowo na realistycznych danych i tworzy użyteczną tabelę danych wyjściowych.

Test dymny w małej puli

Uruchom notatnik od początku do końca, aby potwierdzić, że każda komórka wykona się bez błędów:

Uruchom ponownie jądro, aby wyczyścić zalegający stan.
Uruchom wszystkie komórki od góry do dołu — każda komórka musi zostać ukończona bez błędu.

Jeśli komórka transformacji na poziomie Small działa dłużej niż 5 minut, filtry danych wejściowych są zbyt mało restrykcyjne. Zawęź zakres dat lub projekcję kolumn przed skalowaniem.

Weryfikowanie tabeli wyjściowej

Upewnij się, że tabela wyjściowa została utworzona i zawiera oczekiwane dane:

W panelu Lake tables w rozszerzeniu Sentinel odśwież widok i potwierdź, że tabela wyjściowa jest widoczna z oczekiwanym schematem.
Uruchom komórkę weryfikacji:

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 skalowania w puli Średniej lub Dużej

Sprawdź, czy notatnik generuje spójne wyniki przy większych rozmiarach puli:

Uruchom ponownie notatnik w wersji Medium (oraz Large, jeśli rozmiar zbioru danych tego wymaga).
Upewnij się, że liczby wierszy i rozkłady kolumn są zgodne z małym uruchomieniem. Jeśli się różnią, masz niedeterministyczną transformację, która wymaga badania.

Przypadki brzegowe testów

Puste dane wejściowe: wskaż tabelę lub zakres dat z zerowymi wierszami. Notebook powinien zakończyć działanie w kontrolowany sposób lub zapisać pusty wynik — a nie ulec awarii.
Dryf schematu: Jeśli tabela wejściowa zyska dodatkową kolumnę, notebook powinien nadal działać. Nigdy nie zakładaj kolejności pozycyjnej.

Zaplanuj notatnik jako zadanie

Większość opublikowanych rozwiązań opartych na notesach działa zgodnie z harmonogramem — bazowe uruchomienie co godzinę, codzienne skanowanie anomalii itd. Rozszerzenie usługi Sentinel zamienia wszystkie zapisane notesy w zaplanowane zadanie, które działa nienadzorowane w zarządzanej puli Spark.

Tworzenie zadania

Aby przekonwertować notes na zaplanowane zadanie, wykonaj następujące kroki:

Otwórz notatnik w programie VS Code.
Wybierz Utwórz zadanie harmonogramu w notatniku, a następnie, gdy pojawi się monit, wybierz Użyj istniejącego notatnika.

Aby uzyskać więcej informacji, zobacz Tworzenie zadań notesu Jupyter i zarządzanie nimi.

Konfigurowanie zadania

Aby skonfigurować zaplanowane zadanie, wypełnij następujące pola:

Wprowadź Nazwę zadania w formacie kebab-case, która opisuje notatnik (na przykład failed-signin-baseline-hourly).
Wprowadź jednozdaniowy Description opisujący cel zadania i tabelę wyjściową.
Wybierz rozmiar puli platformy Spark, który sprawdzono w trakcie testów. Nie ustawiaj zbyt dużego rozmiaru — zadania są uruchamiane w tej puli przy każdym wywołaniu.
W polu Harmonogram wybierz opcję Na żądanie dla uruchomień ręcznych lub Zaplanowane z częstotliwością (co minutę, co godzinę, codziennie, co tydzień lub co miesiąc).
Wybierz pozycję Prześlij , aby opublikować zadanie.

Weryfikowanie zadania

Po przesłaniu upewnij się, że zadanie działa prawidłowo:

Przejdź do panelu Zadania w rozszerzeniu usługi Sentinel — powinno zostać wyświetlone zadanie.
Wybierz zadanie >Uruchom teraz , aby uruchomić natychmiastową walidację.
Po zakończeniu uruchomienia przejdź do karty Historia uruchomień, aby przejrzeć dzienniki i czasy wykonania.

Important

Przesłane zadania są oddzielone od pliku lokalnego .ipynb . Edytowanie pliku lokalnego nie powoduje zaktualizowania uruchomionego zadania. Aby zaktualizować zadanie: otwórz je w panelu Zadania>Pobierz notatnik> edytuj >Edytuj zadanie>Prześlij, aby przesłać zaktualizowaną wersję.

Wyświetl zadanie w portalu Defender

Przejdź do Microsoft Sentinel>Eksploracja jeziora danych>Zadania. Możesz tutaj włączyć lub wyłączyć harmonogram i wyświetlić historię uruchomień, ale nie możesz edytować notatnika w portalu.

Spakuj i opublikuj rozwiązanie notatnika

Po przetestowaniu i zmaterializowaniu notebooka spakuj go do wdrożenia dla klientów. Aby uzyskać szczegółowe instrukcje dotyczące tworzenia pakietów, zobacz Tworzenie pakietów i publikowanie rozwiązań Microsoft Sentinel dla grafów i notesów.

Troubleshooting

Tworzenie notatnika

Objaw	Prawdopodobna przyczyna i poprawka
`MicrosoftSentinelProvider` nie znaleziono	Rozszerzenie nie zostało zalogowane lub otwarto jądro inne niż Spark. Po wyświetleniu monitu zaloguj się do rozszerzenia Microsoft Sentinel i wybierz środowisko uruchomieniowe Microsoft Sentinel.
Komórka zawiesza się na etapie „Uruchamianie sesji Spark”	Uruchamianie pierwszej komórki trwa od 3 do 5 minut. Po 6 minutach sprawdź wskaźnik wykorzystania jednostek vCore na pasku stanu — pula może działać na granicy pojemności. Spróbuj mniejszego rozmiaru puli.
`save_as_table` kończy się błędem z powodu odmowy dostępu w warstwie analitycznej	Zarządzana tożsamość `msg-resources-<guid>` z jeziorem danych nie posiada Log Analytics Contributor w przestrzeni roboczej Log Analytics. Przypisz je zgodnie z wymaganiami wstępnymi i spróbuj ponownie.
Tabela wyjściowa pojawia się w panelu Lake tables, ale jest pusta	`.filter()` prawdopodobnie usunął wszystkie wiersze. Dodaj wypisanie liczby wierszy bezpośrednio przed `save_as_table`, aby zlokalizować źródło problemu.

Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z notesami.

Planowanie zadań

Objaw	Prawdopodobna przyczyna i poprawka
Zmiany w lokalnym elemencie `.ipynb` nie są uwzględniane w zaplanowanym zadaniu	Przesłane zadania są oddzielone od pliku lokalnego. Pobierz zadanie z programu VS Code, edytuj je, a następnie użyj polecenia Edytuj zadanie>Prześlij , aby przekazać nową wersję.
Zadanie uruchamia się, ale nie generuje żadnych danych wyjściowych	Sprawdź kartę Historia uruchomień w panelu Zadania — dziennik przebiegu zwykle pokazuje komórkę, w której występuje błąd. Najczęstszą przyczyną jest to, że notatnik odczytuje dane z tabeli, do której tożsamość, w kontekście której jest uruchomiony, nie ma dostępu.