建立自訂連接器

支援的國家/地區：

Google SecOps SOAR

注意：本文件假設您具備 Python 和物件導向程式設計的工作知識。

本文說明 SOAR SDK 如何為內容中心可能沒有的第三方工具，建構自訂整合功能。連接器用於從資料來源擷取資料，這些資料來源通常 (但不一定) 會有某種警報佇列。平台會透過連接器與 Google SecOps 應用程式的互動，建立案件、快訊和事件。連結器會擷取基本事件資料、將資料指派給快訊，然後將快訊傳送至 Google SecOps 應用程式及其資料處理管道。

注意：進一步瞭解 TIP Common 程式庫。

如要建立自訂連接器，請按照下列高階步驟操作：

1. 建立 Manager 類別，其中包含第三方工具的 API 邏輯。
2. 使用 IDE 建構連接器。

建立管理員

建立連結器的第一步是建構 Manager 類別，其中包含要整合的技術所需的所有 API 邏輯。舉例來說，Google SecOps 中的 Netskope 整合功能包含預先建構的管理員。這個管理工具包含與 Netskope API 互動所需的所有邏輯，可做為您自行實作時的範本。

建立連接器

在 IDE 中，按照「建構自訂整合」一文的說明建立新的連接器。IDE 會產生一般範本，其中包含程式碼註解，說明連接器指令碼的基本結構和需求。

雖然連接器邏輯可能有所不同，但程序通常包含下列核心步驟：

1. 使用第三方工具的 API 擷取快訊、偵測結果或事件。如果是 Netskope，則是由 get_alerts() 方法處理。為確保不會重複發出快訊，請依時間戳記傳送查詢，並在每次執行後更新查詢。
2. 使用 AlertInfo (舊稱 CaseInfo) 類別建立快訊，並指派所有必要欄位
3. 擷取並平坦化相關聯的事件資料，避免巢狀清單和字典發生問題，然後將平坦化的事件附加至快訊。
4. 依時間排序快訊，並儲存最新的時間戳記，以用於下一個查詢。

注意：快訊可包含多個事件。舉例來說，SIEM 平台會將多個事件相互關聯，形成單一警報 (例如 Trellix ESM) 或違規事項 (例如 QRadar)。相較之下，端點偵測工具通常會針對每則快訊產生一個事件。連接器邏輯應反映資料來源的結構。

匯入和 SDK

每個連接器都必須執行下列操作：

• 從 SiemplifyConnectors 匯入 SiemplifyConnectorExecution 類別。這個類別通常會在連接器的 main() 函式中例項化。這個物件會使用 return_package() 方法將警報清單傳遞至 Google SecOps 應用程式，腳本也會隨即結束。
• 從 SiemplifyConnectorsDataModel 匯入 AlertInfo 類別。建立這個類別的例項會建立警示物件。在本範例中，為避免與來源系統的內建警報物件 (Netskope) 混淆，已將其重新命名為 SiemplifyAlertInfo，但這項重新命名作業為選用。

SiemplifyUtils 模組提供常用的記錄、處理資料格式、時間轉換等方法。建議您匯入 output_handler、dict_to_flat 和 unix_now，因為這些函式對於核心功能 (包括時間處理) 至關重要。

大多數連接器也會匯入整合的 Manager 類別。部分整合項目包含多位管理員。您也可以視用途匯入其他標準 Python 程式庫。

注意：舊版連接器可以使用 SiemplifyConnectors 中的 CaseInfo。這個類別與 AlertInfo 相同，反映的是已淘汰的命名慣例。

常數變數

建議您宣告幾個常數變數，以供日後使用。

圖 1：常數變數

建立 Google SecOps 快訊的指令碼範例

如先前所述，建立快訊的方法是將 AlertInfo 類別的物件例項化。在本範例中，這個屬性已重新命名為 SiemplifyAlertInfo()，以免與來源系統混淆。alert_info 物件包含多個必要屬性，必須定義這些屬性，應用程式才能正確處理快訊。build_alert_info 函式會收到 Netskope 快訊 (以原始 JSON 格式從 API 接收)，以及 Siemplify 物件做為輸入。然後剖析 Netskope 快訊，並將相關值指派給 `alert_info` 欄位。

這個函式也會使用先前定義的常數。在 alert_info 物件上設定的所有屬性，都會成為 Google SecOps 應用程式內警報物件的一部分。

圖 2 的第 35 行標示了這個程序的重要部分：使用 dict_to_flat 方法將快訊扁平化，然後附加至 events 屬性。

圖 2：建立快訊的指令碼範例

 

快訊可能包含多個事件，因此您必須加入適當處理每個事件的邏輯。在本例中，每則快訊只包含一個事件，因此預設實作項目就已足夠。

dict_to_flat 方法用於將原始 JSON 結構扁平化。這有助於避免巢狀清單和字典的問題。扁平化鍵/值組合是原始組合的稍作修改版本。

請參閱圖 2 中的下列邏輯：

• 系統會使用 uuid 程式庫，為 display_id 指派隨機產生的值。Netskope 快訊不會提供 UUID 欄位，但如果有的話，可以改用該欄位。
• ticket_id將同樣捐出 display_id。 系統中每個快訊的這兩個欄位都不得重複。系統會產生隨機 UUID，確保 ID 不重複。
• name 是快訊名稱，會顯示在 GUI 中。
• rule_generator 是指在來源系統中產生快訊的規則。原始資料中不一定會顯示這個欄位。如果缺少這項屬性，你可以指派任何字串值，但不得留空。
• start_time 和 end_time 代表快訊的時間戳記。在本例中，Netskope 警報提供的是 Unix Epoch 時間戳記，必須乘以 1000 才能轉換為毫秒。這是 Google SecOps 的預期格式。如果來源使用其他格式，您必須轉換格式。如需實用的時間轉換方法，請參閱 SiemplifyUtils.py 模組。
• priority：Google SecOps 應用程式會根據快訊的優先順序，為每個案件指派優先順序。Google SecOps API 會使用下列配置將數值對應至視覺標籤，其中整數值會傳遞至連接器： {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}，其中整數值會傳遞至連接器。 舉例來說，傳遞 `100` 會在 GUI 中將快訊標示為「重大」。在這個連接器中，額外的輔助函式會使用 `SEVERITY_MAP` 常數，將 Netskope 的嚴重程度值對應至這個優先順序等級。不過，由於 Netskope 的嚴重程度欄位不一致，因此對應需要額外的邏輯來評估多個欄位。
• device_vendor 和 device_product 會從指令碼中先前定義的常數指派值。
• 在 Google SecOps 中使用多個環境時，environment 至關重要。在本例中，這個值來自 siemplify 物件，並與平台中為連接器選取的環境一致。
• 在第 37 行 (圖 3)，連接器會新增鍵 product_name，並將值設為「Netskope」，藉此修改基本事件字典。這是必要步驟，因為原始資料不包含一致的產品欄位，無法用於平台本體中的對應和建模。

  

  圖 3：修改基本事件

執行連接器的指令碼範例

main 函式包含連接器的核心執行邏輯：

• output_handler 裝飾器用於偵錯，本文不予說明。
• main 函式包含選用參數 is_test_run，預設值為 False。顧名思義，這項參數會決定連接器應在正式環境中擷取快訊，還是從應用程式的「連接器測試」分頁中以測試模式執行。

請查看每行指令碼的核心執行邏輯細目：

圖 3：修改基本事件

• 第 56 和 57 行會初始化執行期間使用的兩個空白清單。
• 在第 58 行，SiemplifyConnectorExecution 類別會例項化 siemplify 物件。這個物件會管理大部分的連接器執行階段行為。
• 在第 61 行，系統會建立 Connector Allowlist 的執行個體。雖然這個連接器不會使用，但其他連接器通常會使用，因此本指南不會討論。
• 在第 67 至 69 行中，系統會為連接器參數定義變數，例如驗證憑證或設定。
• 第 71 行會例項化 NetskopeManager 物件，並傳遞相關參數，以順利完成驗證。本範例未顯示處理驗證的內部管理員邏輯。
• 在第 73 行中，系統會從先前執行連接器時建立的本機檔案擷取時間戳記。這個時間戳記是用來避免重複處理相同的快訊。
• 在第 74 和 75 行中，系統會處理連接器首次執行且尚未設定時間戳記的情況 (例如預設為 `0` 時)。由於 Netskope 需要 Unix Epoch 時間，且不接受 `0` 做為有效開始時間，因此系統會使用 `unix_now` 函式以毫秒為單位擷取目前時間。這個值會除以 `1,000`，轉換為 Unix 紀元秒數。然後，產生的開始和結束時間會傳遞至管理工具中的 `get_alerts` 方法。雖然許多 API 只接受開始時間，但 Netskope API 需要開始和結束時間，才能查詢以時間為準的快訊。
注意：時間和時間戳記處理是建構連結器時最複雜的環節之一。不同的第三方系統會以各種格式傳回時間戳記，有些系統可能不支援根據傳回的格式進行查詢。充分瞭解來源系統的 API 至關重要。
• 第 77 行會從 Netskope 擷取快訊清單。如果連接器以測試模式執行，系統只會選取清單中的最後一個快訊 (第 79 至 80 行)。

溢位邏輯

然後，連接器會逐一處理擷取的快訊，並使用先前定義的 build_alert_info 函式，從每個快訊建構快訊。這會將每個快訊附加至先前初始化的 all_alerts 清單。連接器邏輯的下一個部分會處理溢位。
溢位是一種門檻機制，可防止系統在短時間內擷取過多快訊，尤其當快訊共用相同的環境、產品和規則產生器時，更需要這項機制。雖然並非必要，但我們建議您實作溢位邏輯，以防效能降低。

請參閱圖 4，瞭解每個指令碼行的溢位邏輯細目：

• 在第 104 至 105 行中，如果 alert 未分類為溢位，則會附加至要擷取的快訊清單。



圖 4：溢位機制。

結束連接器執行作業

如果連接器未在測試模式下執行，則必須更新時間戳記，以反映擷取的最後一則快訊。這樣可確保在下一個執行週期內，系統不會重新擷取相同的快訊。all_alerts 清單會依時間戳記排序，因此即使溢位警報也會有助於判斷最新時間戳記。

如圖 5 所示，請依據指令碼行細分查看連接器執行邏輯：

• 在第 126 行，系統會將非溢位警報清單提交給應用程式，然後在 GUI 中建立並顯示警報。
• 在第 128 至 131 行中，他們會判斷連接器是否以測試模式執行。系統會使用應用程式傳遞的系統引數 (例如點選「測試」分頁中的「執行連接器一次」) 進行判斷。
  

  

  圖 5：結束連接器執行作業

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。