建立自訂連接器

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

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

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

建立管理員

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

建立連接器

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

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

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

匯入和 SDK

每個連接器都必須符合下列條件：

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

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

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

常數變數

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

建立 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 屬性。

 

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

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 紀元時間戳記，必須乘以 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」，藉此修改基本事件字典。這是必要步驟，因為原始資料不包含可用於平台本體對應和建模的產品欄位。

  

執行連接器的指令碼範例

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

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

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

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

溢位邏輯

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

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

• 在第 104 至 105 行，如果 alert 未歸類為溢位，則會附加至要擷取的警告清單。

結束連接器執行作業

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

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

• 在第 126 行，系統會將未溢位的快訊清單提交給應用程式，然後在 GUI 中建立並顯示快訊。
• 第 128 至 131 行會判斷連接器是否在測試模式下執行。系統會根據應用程式傳遞的系統引數 (例如在「測試」分頁中點選「執行連接器一次」) 做出這項判斷。