為 Microsoft Sentinel 開發筆記型電腦解決方案

作為 ISV 合作夥伴，您可以建置、測試、包裝並發布 Jupyter 筆記型電腦分析解決方案，並以 SaaS 服務的方式在 Microsoft 安全性 Store 上發布。 Microsoft Sentinel 資料湖支援在受控 Spark 集區上針對大型安全性資料集執行的 Jupyter Notebook。 這些筆記本非常適合用於低速且緩慢的攻擊偵測、行為基線分析、AI/ML 分析、敏感資料路徑映射、資料視覺化，以及傳統 KQL 偵測無法表達的豐富功能。

筆記型電腦平台解決方案通常設計用於歷史分析、複雜的資料轉換及重複的資料處理工作流程。 它會將輸出寫入資料湖中的自訂資料表，讓下游分析規則、搜捕查詢、Security Copilot 代理程式或 MCP 工具能利用筆記本解決方案的結果。 您提交至合作夥伴中心的 .zip 套件會宣告為 SentinelLake 類型，其中包含 Notebook，以及 Notebook 所需下游 Azure 資源的選用 ARM 範本。

本文將帶你了解如何建置、測試、打包，以及將 Microsoft Sentinel 平台筆記本解決方案發佈到 Microsoft 安全性 Store。 完成本指南後，您將獲得：

  • 一台可運作的 Jupyter 筆記本，能讀取 Sentinel 資料湖的資料
  • 在受控 Spark 集區上執行 Notebook 的排程作業
  • SentinelLake 套件 ZIP 檔 (PackageManifest + Notebook 資料夾)
  • Microsoft 安全性 Store 中的合作夥伴中心 SaaS 供應項目清單

先決條件

您的租用戶必須上線至 Microsoft Sentinel 資料湖。 請在 Defender 入口網站確認您的入職狀態。 請前往 系統>設定>Microsoft Sentinel>資料湖。 如果您的租用戶已就緒，狀態會顯示為 [已佈建]。 如需上線指示，請參閱上線至 Microsoft Sentinel 資料湖。

所需的權限

運作/資源 所需角色
上線至 Sentinel 資料湖 Microsoft Entra ID - 安全性系統管理員或全域管理員
將 Sentinel 工作區上線至 Defender 入口網站 訂用帳戶範圍的訂用帳戶擁有者或使用者存取系統管理員，以及訂用帳戶或資源群組範圍的 Microsoft Sentinel 參與者
將 Sentinel 工作區上線至資料湖 訂用帳戶或資源群組範圍的訂用帳戶擁有者或 Microsoft Sentinel 參與者
在資料湖上執行 Notebook Microsoft Sentinel 閱讀者或貢獻者
Log Analytics 工作區（用於回寫至分析層級） 指派給資料湖受控識別 msg-resources-<guid> 的 Log Analytics 參與者角色
Microsoft合作夥伴中心 Marketplace Publisher 帳戶 (一次性使用；與 Security Copilot 發佈所使用的帳戶相同)

Note

執行一次性的資料湖導入作業時，必須具備訂用帳戶擁有者角色。 使用 Microsoft Entra Privileged Identity Management（PIM）在需要時暫時升格為此角色，完成入職後再移除存取權限。

必要工具

  • Visual Studio Code。
  • Microsoft Sentinel VS Code extension
  • 推薦使用 GitHub Copilot VS Code 擴充功能來加速筆記本撰寫。
  • Python 3.10+ 已安裝於本地。 Spark 核心在 Azure 上運行，但 VS Code 需要本地直譯器來編輯 cell。

流程概觀

發佈程序從在本機開發 Notebook 開始，最終建立可在 Microsoft 安全性 Store 中找到的已封裝 SaaS 供應項目。

  1. 本地筆記本開發（VS Code + Sentinel 擴充功能）
  2. 以互動方式針對 Sentinel 平台執行
  3. 使用具代表性的資料進行測試；驗證輸出資料表已填入資料
  4. 排程為作業 (隨選或排程)
  5. 封裝為 SentinelLake .zip（PackageManifest.yaml + 資料夾）
  6. 在 Microsoft Partner Center 建立 SaaS 方案
  7. 上傳套件、建立元資料、規劃與定價
  8. 審核與發佈、自動審核、立即上線
  9. 在 Microsoft 安全性 Store 中上架

安裝 Visual Studio Code 和 Microsoft Sentinel 延伸模組

所有筆記型電腦開發皆在本地 VS Code 進行，並安裝 Microsoft Sentinel 擴充功能。 Spark 核心在 Azure 中運行——VS Code 是編輯器和提交客戶端。

  1. 從 https://code.visualstudio.com/ 下載 Visual Studio Code，並以預設選項安裝。

  2. 開啟 VS Code >擴充套件 市集（Ctrl+Shift+X 或 Cmd+Shift+X）。

  3. 搜尋 Sentinel 並安裝 Microsoft Sentinel 擴充功能（publisher： ms-security）。

    安裝完成後，Microsoft Sentinel 圖示會出現在左側工具列。

  4. （推薦）在市集搜尋 GitHub Copilot，安裝它，並在提示時登入 GitHub。

    Copilot 了解 MicrosoftSentinelProvider API，並會自動完成 PySpark 轉換作業。

  5. 在左側工具列選擇 Microsoft Sentinel 圖示。

  6. 核准登入對話方塊，然後選取在工作區中具有 Sentinel 讀取者/參與者角色的帳戶。

左側窗格會顯示 [資料湖資料表] 和 [作業]，表示延伸模組已成功連線至資料湖。

Microsoft Sentinel VS Code 擴充套件的截圖，顯示 Lake 表格、工作和圖表區塊。

Caution

如果您已登入多個來賓租用戶，在 VS Code 左下角切換帳戶會終止所有作用中的 PySpark 工作階段；切換後必須重新啟動核心。 請安排在兩次執行之間切換帳戶，不要在執行期間切換。

開發你的筆記本

筆記本採用以下撰寫模式：

  • 將資料湖資料表讀取至 Spark DataFrame
  • 使用 PySpark 進行轉換
  • 可選擇性地加入外部資料
  • 將結果寫入一個 Sentinel 可以使用的自訂資料表

探索 [資料湖資料表] 面板

要辨識筆記本使用的輸入表，請瀏覽 Lake 表格面板：

  1. 選擇哨兵圖示並展開 湖泊表格。
  2. 表格依資料庫與類別（系統、自訂、聯邦）分組。 選擇任一表格以查看其欄位定義與類型。
  3. 找出筆記本讀取的輸入表，並記下確切名稱。

建立新的筆記本

要為你的解決方案建立新的 Jupyter 筆記本，請完成以下步驟：

  1. 按 Ctrl+Shift+P / Cmd+Shift+P> 輸入「建立新 Jupyter Notebook」，或選擇「新>檔案>Jupyter Notebook」。

    VS Code 的截圖顯示 Create New Jupyter Notebook 指令。

  2. 將筆記本儲存為描述性名稱（例如）。 failed-signin-baseline.ipynb

讀一張表格

把這個範本貼到第一個儲存格，然後把表格名稱換成你的：

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)

選取執行階段集區並執行儲存格

若要針對資料湖執行此儲存格，請選取一個集區並提交：

  1. 選取儲存格上的 Run 三角形圖示。

  2. 出現提示時，請選擇 Microsoft Sentinel 作為執行階段。

    VS Code 的截圖顯示執行時選擇。

  3. 選擇池大小： 小型 用於探索， 中 型用於轉換， 大型 用於機器學習或數千萬列的聚合。

第一次執行需要 3 至 5 分鐘才能啟動 Spark 工作階段。 後續的儲存格會在幾秒內執行完畢。

轉換並寫回自訂資料表

此 save_as_table() 方法將 DataFrame 寫入湖區（或分析層）的自訂資料表。 目的資料表會在第一次寫入時建立。

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

筆記本撰寫範式

以下模式涵蓋最常見的情境：

Pattern 何時使用它
基準線 + 漂移 計算每位使用者或每台主機的正常行為基準；標示偏離基準的資料列。 Classic 用於登入失敗與程序執行分析。
跨資料表聯結 使用共用實體 (UPN、主機、IP)，將您擁有的資料湖資料表與內建資料表 (SigninLogs、SecurityAlert、DeviceProcessEvents) 聯結。
ML 計分 在筆記本中訓練或載入預訓練模型;每行計分;將頂N列的風險列寫入自訂輸出表以供下游警示。
視覺調查 使用 matplotlib 或 plotly 繪製時間軸、熱力圖與過程樹;將筆記本匯出成 HTML 以便交接。

Tip

大量使用 markdown 儲存格來記錄你的程式碼。 Security Store 的審查員——以及負責管理你筆記本的 SOC 分析師——需要在不讀程式碼的情況下，了解每個區塊的功能。 在每個程式碼區塊上方放置一個標記格，說明目的、輸入、輸出和預期輸出。 如果 Notebook 內容不清楚，檢閱者會直接判定為不合格。

測試筆記型電腦

測試需要證明筆記本能在真實數據上端到端運行，並產生可用的輸出表。

小泳池的煙霧測試

請將筆記本從頭到尾執行一遍，確認每個儲存格都能順利完成且沒有錯誤：

  1. 重新啟動核心以清除任何過時狀態。
  2. 從上到下執行所有儲存格——每個儲存格都必須在不發生錯誤的情況下完成執行。

如果某個轉換單元在 Small 下執行時間超過 5 分鐘，表示你的輸入篩選條件過於寬鬆。 在擴大規模之前，請先縮小日期範圍或欄位投影。

驗證輸出表

確認輸出表已建立並包含預期資料：

  1. 在 Sentinel 擴充套件的 Lake 表格 面板中，重新整理並確認你的輸出表格是否以預期的結構顯示。
  2. 執行驗證儲存格：
verify_df = data_provider.read_table("EntraGroups_Processed_SPRK")
print("Row count:", verify_df.count())
verify_df.printSchema()
verify_df.show(5, truncate=False)

在中型或大型集區上進行規模測試

確認 Notebook 在較大的集區大小下會產生一致的結果：

  1. 在中型集區上重新執行 Notebook (如果資料集的規模有此需要，也請在大型集區上重新執行)。
  2. 確認列數和欄位分布是否與小批量相符。 如果它們出現分歧，表示存在需要進一步調查的非決定性轉換。

測試極端情況

  • 空輸入：指向一個沒有列的表格或日期範圍。 Notebook 應正常處理失敗或寫入空白輸出，而不應當機。
  • 結構描述漂移：如果輸入資料表新增資料行，Notebook 仍應能執行。 絕不要假設位置順序。

將 Notebook 排程為作業

大多數已發布的 Notebook 解決方案都是依排程執行，例如每小時執行基準作業、每日進行異常掃描等等。 Sentinel 擴充功能會將任何已儲存的筆記本轉換為可在受控 Spark 集區上無人值守執行的排程作業。

建立作業

要將筆記本轉換成排程工作，請完成以下步驟：

  1. 在 VS Code 中開啟筆記本。
  2. 在筆記本中選擇 建立排程工作 ，然後在提示時選擇 使用現有筆記本 。

如需詳細資訊，請參閱 建立和管理 Jupyter 筆記本任務。

一張截圖，展示如何在筆記本中建立排程工作。

設定作業

要設定排程工作，請填寫以下欄位：

  1. 輸入採用 kebab-case 格式且能描述 Notebook 的作業名稱 (例如 failed-signin-baseline-hourly)。
  2. 輸入一句話的 說明 ，涵蓋工作的目的與產出表。
  3. 選擇你在測試時驗證過的 Spark 池大小 。 請勿選用過大的集區，因為每次叫用作業時，都會在此集區上執行。
  4. 對於 排程，若要手動執行，請選擇 隨選；或者選擇 已排程，並設定重複頻率（每分鐘、每小時、每日、每週或每月）。
  5. 選擇 提交 以發佈職缺。

驗證作業

提交後，請確認工作是否正確執行：

  1. 切換到 Sentinel 擴充功能中的 職缺 面板——你的職缺應該會出現。

  2. 立即選擇「>」工作以進行即時驗證。

  3. 一張截圖，示範如何立即執行筆記本作業。

  4. 運行結束後，切換到 運行歷史 標籤查看日誌與時間。

Important

提交的工作會與你本地 .ipynb 檔案解耦。 編輯本地檔案並不會更新執行中的任務。 若要更新作業：在 [作業] 面板中開啟作業 > [>下載 Notebook>] 編輯 [>編輯作業>提交]，以上傳更新後的版本。

請在 Defender 入口網站查看職缺

瀏覽至 [Microsoft Sentinel>資料湖探索>作業]。 你可以在這裡啟用或停用排程並查看運行歷史，但無法從入口網站編輯筆記本。

打包並發布你的筆記本解決方案

一旦你的筆記本測試完成並實體化，就打包後部署給客戶。 如需詳細的打包說明，請參閱「打包並發佈 Microsoft Sentinel 圖形與筆記本解決方案」。

故障排除

筆記本編寫

症狀 可能的原因與解決方法
MicrosoftSentinelProvider 未找到 擴充功能未登入，或是你開啟了非 Spark 核心。 登入 Microsoft Sentinel 擴充功能，並在提示時選擇 Microsoft Sentinel 執行環境。
儲存格停滯於「正在啟動 Spark 工作階段」 首次啟動需要 3 到 5 分鐘。 6分鐘後，請查看狀態列中的vCore使用率指示器——你的泳池可能已滿。 試試小一點的泳池。
save_as_table 在分析層因權限遭拒而失敗 資料湖受控身分識別msg-resources-<guid>在記錄分析工作區沒有記錄分析參與者。 依據 先決條件 指派，然後重試。
輸出表會出現在 湖表 面板，但是空的 .filter() 很可能移除了所有列。 在 save_as_table 前面緊接著新增資料列計數輸出，以找出問題所在。

更多資訊請參見 Notebooks 故障排除。

工作排程

症狀 可能的原因與解決方法
對本地 .ipynb 的編輯未反映在排程工作中 提交的工作會與本地檔案解耦。 從 VS Code 下載工作，編輯後再用編輯工作>提交上傳新版本。
作業執行但未產生任何輸出 請查看工作面板中的 「執行歷史」 標籤——執行日誌通常 會 顯示失敗的儲存格。 最常見的原因是 Notebook 從執行身分無權存取的資料表讀取資料。

更多資訊請參見 Notebooks 故障排除。

相關內容

  • 上次更新時間：