Mengembangkan solusi notebook untuk Microsoft Sentinel

Sebagai mitra ISV, Anda dapat membuat, menguji, mengemas, dan menerbitkan solusi analitik notebook Jupyter ke Microsoft Security Store sebagai penawaran SaaS. Data lake Microsoft Sentinel mendukung notebook Jupyter yang berjalan pada kumpulan Spark terkelola terhadap himpunan data keamanan besar. Notebook ini ideal untuk deteksi serangan rendah dan lambat, baselining perilaku, analitik berbasis AI/ML, pemetaan jalur data sensitif, visualisasi data, dan pengayaan yang tidak dapat diekspresikan oleh deteksi KQL tradisional.

Solusi platform notebook biasanya dirancang untuk analisis historis, transformasi data yang kompleks, dan alur kerja pemrosesan data berulang. Perangkat ini menulis output ke tabel khusus di data lake, di mana aturan analitik hilir, pencarian kueri, agen Security Copilot, atau alat MCP dapat mengonsumsi hasil dari solusi notebook. Paket .zip yang Anda kirimkan ke Partner Center ditetapkan sebagai tipe SentinelLake dan berisi notebook serta, secara opsional, templat ARM untuk sumber daya Azure downstream yang diperlukan oleh notebook.

Artikel ini membimbing Anda membangun, menguji, mengemas, dan menerbitkan solusi notebook platform Microsoft Sentinel ke Microsoft Security Store. Setelah menyelesaikan panduan ini, Anda akan memiliki:

Notebook Jupyter yang berfungsi yang membaca data dari data lake Sentinel
Tugas terjadwal yang menjalankan notebook di pool Spark terkelola
Zip SentinelLake paket (PackageManifest + folder buku catatan)
Cantuman penawaran SaaS Partner Center di Microsoft Security Store

Prasyarat

Tenant Anda harus sudah diintegrasikan ke dalam data lake Microsoft Sentinel. Verifikasi status onboarding Anda di portal Defender. Navigasi kePengaturan>Sistem>Microsoft Sentinel>Data lake. Status berbunyi Disediakan jika penyewa Anda siap. Untuk petunjuk orientasi awal, lihat Orientasi awal ke data lake Microsoft Sentinel.

Memerlukan izin

Operasi/Sumber Daya	Peran yang diperlukan
Onboard ke danau data Sentinel	Microsoft Entra ID - Administrator Keamanan atau Administrator Global
Sertakan ruang kerja Sentinel ke portal Defender	Pemilik Langganan, atau Administrator Akses Pengguna pada cakupan langganan dan Kontributor Microsoft Sentinel pada cakupan langganan atau grup sumber daya
Tambahkan ruang kerja Sentinel ke Data Lake	Pemilik Langganan atau Kontributor Microsoft Sentinel pada cakupan langganan atau grup sumber daya
Menjalankan buku catatan di data lake	Pembaca atau Kontributor Microsoft Sentinel
ruang kerja Log Analytics (untuk penulisan kembali ke tingkat analitik)	Log Analytics Contributor yang ditugaskan ke identitas terkelola data-lake `msg-resources-<guid>`
Pusat Mitra Microsoft	Akun penerbit Marketplace (sekali saja; akun yang sama digunakan untuk menerbitkan agen Security Copilot)

Note

Peran Pemilik Langganan diperlukan untuk tugas onboarding data lake yang dilakukan sekali saja. Gunakan Microsoft Entra Privileged Identity Management (PIM) untuk meningkatkan peran ini sementara hanya jika diperlukan, lalu hapus akses setelah onboarding selesai.

Alat yang diperlukan

Visual Studio Code.
ekstensi Microsoft Sentinel VS Code
Ekstensi GitHub Copilot VS Code direkomendasikan untuk mempercepat pembuatan notebook.
Python 3.10+ diinstal secara lokal. Kernel Spark berjalan di Azure tetapi VS Code memerlukan penerjemah lokal untuk pengeditan sel.

Gambaran umum proses

Proses penerbitan dimulai dari pengembangan notebook lokal yang kemudian berlanjut menjadi penawaran SaaS dalam bentuk paket yang dapat ditemukan di Microsoft Security Store.

Pengembangan buku catatan lokal (ekstensi Visual Studio Code + Sentinel)
Jalankan secara interaktif di platform Sentinel
Uji terhadap data perwakilan; memvalidasi tabel output yang diisi
Jadwalkan sebagai Tugas (sesuai permintaan atau terjadwal)
Kemas sebagai SentinelLake .zip (PackageManifest.yaml + folder)
Membuat Penawaran SaaS di Pusat Mitra Microsoft
Unggah paket, buat metadata, paket langganan, dan harga
Tinjau dan Terbitkan, tinjauan otomatis, Go Live
Tinggal di Microsoft Security Store

Menginstal Visual Studio Code dan ekstensi Microsoft Sentinel

Semua pengembangan notebook terjadi secara lokal di Visual Studio Code dengan ekstensi Microsoft Sentinel terinstal. Kernel Spark berjalan di Azure—VS Code adalah klien editor dan pengiriman.

Unduh Visual Studio Code dari https://code.visualstudio.com/ dan instal dengan opsi default.
Buka marketplace > Visual Studio Code (Ctrl+Shift+X atau Cmd+Shift+X).
Cari Sentinel dan instal ekstensi Microsoft Sentinel (penerbit: ms-security).

Setelah penginstalan, ikon Microsoft Sentinel muncul di toolbar kiri.
(Disarankan) Cari GitHub Copilot di marketplace, instal, dan masuk ke GitHub saat diminta.

Copilot mengenal API MicrosoftSentinelProvider dan melengkapi transformasi PySpark secara otomatis.
Pilih ikon Microsoft Sentinel di toolbar kiri.
Setujui dialog masuk, lalu pilih akun dengan Pembaca Sentinel / Kontributor di ruang kerja Anda.

Panel sebelah kiri menampilkan Lake tables dan Jobs, yang mengonfirmasi bahwa ekstensi telah menjangkau data lake.

Caution

Jika Anda memiliki beberapa penyewa tamu yang masuk, mengalihkan akun di kiri bawah VISUAL Code akan mematikan sesi PySpark aktif—Anda perlu memulai ulang kernel setelah beralih. Akun paket berlangganan berpindah di antara proses eksekusi, bukan saat proses berlangsung.

Kembangkan notebook Anda

Notebook menggunakan pola penulisan ini:

Membaca tabel data-lake ke dalam Spark DataFrame
Transformasi dengan PySpark
Secara opsional memperkaya dengan data eksternal
Menulis hasil ke tabel kustom yang dapat dikonsumsi Sentinel

Jelajahi panel tabel Lake

Untuk mengidentifikasi tabel input yang digunakan buku catatan Anda, jelajahi panel tabel Lake:

Pilih ikon Sentinel dan perluas tabel Lake.
Tabel dikelompokkan menurut database dan kategori (Sistem, Kustom, Federasi). Pilih tabel apa pun untuk melihat definisi dan jenis kolomnya.
Identifikasi tabel input yang dibaca buku catatan Anda dan catat nama yang tepat.

Buat notebook baru

Untuk membuat notebook Jupyter baru untuk solusi Anda, selesaikan langkah-langkah berikut:

Tekan Ctrl+Shift+P / Cmd+Shift+P> type Create New Jupyter Notebook, atau pilih File>File> Baru Jupyter Notebook.
Simpan buku catatan dengan nama deskriptif (misalnya, failed-signin-baseline.ipynb).

Baca tabel

Tempelkan templat ini ke sel pertama dan ganti nama tabel dengan templat Anda:

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)

Pilih kumpulan runtime dan jalankan sel

Untuk menjalankan sel pada data lake, pilih kumpulan dan kirimkan:

Pilih segitiga "Jalankan" pada sel.
Saat diminta, pilih Microsoft Sentinel sebagai runtime.
Pilih ukuran kumpulan: Kecil untuk eksplorasi, Sedang untuk transformasi, Besar untuk ML atau agregasi lebih dari puluhan juta baris.

Saat pertama kali dijalankan, proses ini memerlukan 3 hingga 5 menit untuk memulai sesi Spark. Sel-sel berikutnya dijalankan dalam hitungan detik.

Mengubah dan menulis kembali ke tabel kustom

Metode save_as_table() ini menulis DataFrame ke tabel kustom di lapisan lake (atau lapisan analitik). Tabel tujuan dibuat saat penulisan pertama.

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

Pola penulisan buku catatan

Pola berikut mencakup skenario yang paling umum:

Pola	Kapan harus menggunakannya
Garis dasar + pergeseran	Hitung perilaku normal setiap pengguna atau host; tandai baris yang menyimpang dari garis dasar. Klasik untuk analitik upaya masuk yang gagal dan eksekusi proses.
Gabungan lintas tabel	Gabungkan tabel lake yang Anda miliki dengan tabel bawaan (SigninLogs, SecurityAlert, DeviceProcessEvents) pada entitas bersama (UPN, host, IP).
Penilaian ML	Latih atau muat model pralatih di notebook; beri skor pada setiap baris; tulis N baris dengan risiko tertinggi ke tabel keluaran kustom untuk pembuatan peringatan lanjutan.
Investigasi visual	Buat linimasa, peta panas, dan pohon proses dengan matplotlib atau plotly; ekspor notebook sebagai HTML untuk serah terima.

Tip

Gunakan sel markdown secara liberal untuk mendokumenkan kode Anda. Peninjau Security Store—dan analis SOC yang menjalankan notebook Anda—perlu memahami fungsi tiap bagian tanpa harus membaca kode. Tempatkan sel markdown di atas setiap blok kode yang menjelaskan tujuan, input, output, dan output yang diharapkan. Peninjau memperlakukan notebook yang tidak jelas sebagai kegagalan yang sulit.

Uji laptop

Pengujian mengharuskan pembuktian bahwa notebook berjalan secara end-to-end pada data yang realistis dan menghasilkan tabel keluaran yang dapat digunakan.

Smoke test pada Small pool

Jalankan notebook dari awal hingga akhir untuk memastikan setiap sel dapat dijalankan hingga selesai tanpa kesalahan:

Mulai ulang kernel untuk menghapus status kedaluarsa apa pun.
Jalankan semua sel dari atas ke bawah—setiap sel harus selesai tanpa kesalahan.

Jika sel transformasi membutuhkan waktu lebih dari 5 menit pada Small, filter input Anda terlalu longgar. Perketat proyeksi tanggal atau kolom sebelum meningkatkan skala.

Validasi tabel keluaran

Konfirmasikan bahwa tabel output telah dibuat dan berisi data yang diharapkan:

Di panel tabel Lake pada ekstensi Sentinel, segarkan dan pastikan tabel keluaran Anda muncul dengan skema yang diharapkan.
Jalankan sel verifikasi:

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

Tes skala pada kumpulan Sedang atau Besar

Pastikan notebook menghasilkan hasil yang konsisten pada ukuran pool yang lebih besar:

Jalankan ulang notebook pada Medium (dan Large jika set data Anda memerlukannya).
Pastikan jumlah baris dan distribusi kolom sesuai dengan proses skala kecil. Jika keduanya berbeda, Anda memiliki transformasi yang bersifat non-deterministik dan perlu ditelusuri penyebabnya.

Menguji kasus tepi

Input kosong: Arahkan ke tabel atau rentang tanggal dengan baris nol. Notebook harus menangani kegagalan dengan baik atau menghasilkan keluaran kosong—bukan malah mogok.
Perubahan skema: Jika tabel input Anda bertambah satu kolom, notebook seharusnya tetap dapat berjalan. Jangan pernah berasumsi urutan posisi.

Menjadwalkan buku catatan sebagai pekerjaan

Sebagian besar solusi notebook yang dipublikasikan dijalankan menurut jadwal—baseline per jam, pemindaian anomali harian, dan sebagainya. Ekstensi Sentinel mengonversi notebook tersimpan apa pun menjadi tugas terjadwal yang berjalan tanpa intervensi pengguna di kumpulan Spark terkelola.

Membuat pekerjaan

Untuk mengonversi buku catatan menjadi pekerjaan terjadwal, selesaikan langkah-langkah berikut:

Buka buku catatan Anda di Visual Studio Code.
Pilih Buat pekerjaan jadwal di buku catatan, lalu pilih Gunakan buku catatan yang sudah ada saat diminta.

Untuk informasi selengkapnya, lihat Membuat dan mengelola pekerjaan notebook Jupyter.

Mengonfigurasi pekerjaan

Untuk mengonfigurasi pekerjaan terjadwal, isi bidang berikut:

Masukkan Nama tugas dalam format kebab-case yang menjelaskan notebook (misalnya, failed-signin-baseline-hourly).
Masukkan Deskripsi satu kalimat yang mencakup tujuan pekerjaan dan tabel output.
Pilih ukuran kumpulan Spark yang Anda validasi selama pengujian. Jangan berlebihan—pekerjaan berjalan di kumpulan ini setiap pemanggilan.
Untuk Jadwal, pilih Sesuai permintaan untuk eksekusi manual, atau Dijadwalkan dengan frekuensi berulang (menit, per jam, harian, mingguan, atau bulanan).
Pilih Kirim untuk menerbitkan pekerjaan.

Memverifikasi pekerjaan

Setelah mengirimkan, konfirmasikan bahwa pekerjaan berjalan dengan benar:

Beralih ke panel Pekerjaan di ekstensi Sentinel—pekerjaan Anda akan muncul.
Pilih pekerjaan >Jalankan sekarang untuk eksekusi validasi segera.
Setelah eksekusi selesai, beralihlah ke tab Jalankan riwayat untuk memeriksa log dan waktu.

Penting

Pekerjaan yang dikirim dipisahkan dari file lokal .ipynb Anda. Mengedit file lokal tidak memperbarui pekerjaan yang sedang berjalan. Untuk memperbarui job: buka di panel Jobs>Unduh notebook>, edit >Edit job>, lalu Submit untuk mengunggah versi yang diperbarui.

Menampilkan pekerjaan di portal Defender

Buka Microsoft Sentinel>Eksplorasi data lake>Pekerjaan. Anda bisa mengaktifkan atau menonaktifkan jadwal dan menampilkan riwayat eksekusi di sini, tetapi tidak dapat mengedit buku catatan dari portal.

Kemas dan publikasikan solusi notebook Anda

Setelah notebook Anda diuji dan diwujudkan, paketkan untuk penyebaran kepada pelanggan. Untuk instruksi pengemasan terperinci, lihat Mengemas dan menerbitkan solusi grafik dan buku catatan Microsoft Sentinel.

Troubleshooting

Penulisan buku catatan

Gejala	Kemungkinan penyebab dan perbaikan
`MicrosoftSentinelProvider` tidak ditemukan	Ekstensi belum masuk, atau Anda membuka kernel yang bukan Spark. Masuk ke ekstensi Microsoft Sentinel dan pilih runtime Microsoft Sentinel saat diminta.
Sel macet pada "Memulai sesi Spark"	Startup sel pertama membutuhkan waktu 3 hingga 5 menit. Setelah 6 menit, periksa indikator utilisasi vCore di bilah status—pool Anda mungkin sudah mencapai kapasitasnya. Coba ukuran pool yang lebih kecil.
`save_as_table` gagal karena izin ditolak pada tingkat analitik	Identitas terkelola data-lake `msg-resources-<guid>` tidak memiliki Log Analytics Contributor pada ruang kerja Log Analytics. Tentukan itu sesuai dengan prasyarat dan coba lagi.
Tabel output muncul di panel tabel Lake tetapi kosong	`.filter()` kemungkinan menghapus semua baris. Tambahkan pernyataan print untuk jumlah baris tepat sebelum `save_as_table` untuk melokalisasi sumber masalah.

Untuk informasi selengkapnya, lihat Pemecahan masalah Notebook.

Penjadwalan pekerjaan

Gejala	Kemungkinan penyebab dan perbaikan
Perubahan pada lokal `.ipynb` tidak ditampilkan dalam job terjadwal	Pekerjaan yang dikirim dipisahkan dari file lokal. Unduh pekerjaan dari Visual Studio Code, edit, lalu gunakan Edit pekerjaan>Kirim untuk mengunggah versi baru.
Pekerjaan berjalan tetapi tidak menghasilkan output	Periksa tab Riwayat eksekusi di panel Tugas—log eksekusi biasanya menampilkan sel yang gagal. Penyebab yang paling umum adalah notebook membaca dari tabel yang tidak dapat diakses oleh identitas yang digunakan saat ini.