開發自訂轉換器

支援的國家/地區：

Google SecOps SOAR

注意： 這項功能受《Google Security Operations 服務專屬條款》的《正式發布前產品條款》規範。正式發布前的功能只提供部分支援，對正式發布前的功能所做的變更可能與其他正式發布前的版本不相容。詳情請參閱《Google SecOps 技術支援服務指南》和《Google SecOps 服務專屬條款》。
如果您的環境未顯示這項功能，請參閱「管理預覽功能」或與系統管理員聯絡。

您可以在 IDE 中直接建立以 Python 為基礎的自訂轉換函式和邏輯運算子，並在應對手冊中使用，因應複雜多變的使用情境。

擴充功能套件

擴充功能套件是一種特殊整合類型，可做為自訂轉換函式和邏輯運算子的容器。與標準整合不同，擴充功能套件不需要執行個體設定，可以直接從 IDE 建立。

擴充功能包最佳做法

• 合併：建立一個主要擴充功能套件，並在其中新增多個轉換函式或邏輯運算子。
• 分離：如果需要一組不同的 Python 程式庫 (依附元件)，且可能與主要套件衝突，請建立新的擴充功能套件。

重要事項：如要在 IDE 中建立擴充功能套件，必須具備「所有環境」權限。

建立擴充功能套件

如要建立新的擴充功能套件，請按照下列步驟操作：

1. 依序前往「回應」> IDE。
2. 按一下「新增」 「建立新項目」。
3. 從下拉式選單中選取「擴充套件」。
4. 為擴充套件提供專屬名稱。
注意：名稱設定後即無法變更。
5. 按一下 [儲存]。

上傳依附元件

與標準整合功能一樣，擴充套件會在虛擬環境中執行，您可以在其中管理 Python 程式庫。

如要管理程式庫，請按照下列步驟操作：

1. 在 IDE 中開啟「擴充功能套件設定」。
2. 從 PyPi 新增必要的 Python 程式庫，或從電腦上傳。

這個特定擴充功能套件中的所有轉換器和邏輯運算子，都能使用這些依附元件。

匯入與匯出

您可以在 IDE 介面中手動匯入及匯出擴充套件。

注意：如果客戶尚未完成第 2 階段的遷移作業，可能無法匯入及匯出資料。詳情請參閱 SOAR 遷移總覽。

自訂轉換器

自訂轉換器是使用者定義的 Python 函式，可擴充運算式建立工具中的預建函式。您可以在 IDE 中直接建立這些函式，用於擷取及處理資料，並與現有的內建函式搭配使用。

建立自訂轉換器

如要定義新的自訂轉換器，請按照下列步驟操作：

1. 在 IDE 中，找出目標擴充功能套件。
2. 選取目標擴充功能套件，在套件中新增項目。
3. 選取「自訂轉換函式」。
4. 輸入名稱。
注意：名稱設定後即無法變更。
5. 新增說明 (如有需要)。將滑鼠游標懸停在運算式製作工具中的自訂轉換器上時，就會顯示這項資訊。
6. 使用 Python 定義指令碼邏輯。您可以從提供的預設範本開始著手。
   • 如預先定義的範本所示，指令碼必須包含 main 函式。
   • 指令碼必須使用 SDK end 函式，將結果傳回給運算式建構工具。
   • 自訂轉換器的輸入可以是不同類型的（例如，字串或清單）。請確保在您的 main 函數中將其轉換為預期類型。
   • 在 IDE 中，您只能使用轉換器 SDK 方法的一個子集：
     • transformer.extract_param("ParamName"): 用於檢索輸入值。
     • transformer.LOGGER: 用於寫入偵錯日誌。
     • transformer.end(result): 傳回轉換後的值。
7. 建立參數：
   • 每個自訂轉換器函數都包含一個預設的 Input 參數。此參數代表輸入數據，即函數所應用的佔位符。您無法刪除此參數。
   • 此外，您還可以新增可選參數，以便在函數中使用。
8. 文件（可選）：定義表達式產生器的產品內部文件：
   • 預期輸入:描述此轉換器函數期望接收的資料類型（例如，「字串」或「字串清單」）。
   • 預期輸出:描述該函數期望為此轉換器傳回的資料類型（例如，「boolean」）。
   • 使用範例: 提供一個如何呼叫函數的範例（例如，if_empty("new_value")）。

在將自訂轉換函數邏輯套用到 playbook 之前，您可以直接在 IDE 中進行測試。這樣可以驗證你的 Python 腳本是否能正確處理各種輸入類型和參數，並回傳預期結果。

逾時

• 預設逾時: 1 分鐘。
• 最大逾時時間: 3 分鐘。

注意：由於平台會等待函數完成，因此必須盡量縮短執行時間。專注於直接資料轉換，避免繁重的處理或查詢外部資料來源。

在表達式產生器中使用自訂轉換器

儲存後，自訂轉換器會與內建函式一起顯示在運算式建構工具的函式清單中。格式為： ExtensionPackName.TransformerName。將游標懸停在函式上，即可查看根據參數說明產生的說明文件。

支援所有預留位置 (JSON 和非 JSON)

運算式建構工具支援 Playbook 設計工具中顯示的所有預留位置，包括非 JSON 結果。

非 JSON 預留位置：

• 您可以在運算式產生器中手動輸入範例資料，針對各種輸入類型 (字串、清單 (以半形逗號分隔的值) 和 JSON) 測試邏輯。
• 使用輸入類型進行測試，無法保證預留位置會在執行階段傳回該特定類型。
• 大多數預留位置都會解析為字串，但特定類型會根據數量解析為字串或清單 (例如 entity.identifier)。建議一律將這些預留位置的輸入內容視為清單。

注意：範例資料是暫時性的，關閉運算式產生器或儲存運算式後，系統不會儲存範例資料。如果再次開啟建立工具，就必須重新輸入範例資料。

處理錯誤

如果自訂轉換函式在執行期間發生錯誤，使用該轉換器的劇本動作就會失敗。Python 指令碼產生的特定錯誤訊息會顯示在劇本執行檢視畫面中，方便您直接排解邏輯問題。

自訂邏輯運算子

自訂邏輯運算子可讓您定義自己的布林邏輯，用於比較值。

建立自訂邏輯運算子

如要定義新的邏輯運算子，請按照下列步驟操作：

1. 在 IDE 中找出目標「擴充功能套件」。
2. 選取「自訂邏輯運算子」。
3. 輸入名稱。
注意：名稱設定後即無法變更。
4. 選用：在 Playbook 設計工具中，為邏輯運算子選單新增說明。
5. 使用 Python 定義指令碼邏輯。您可以從提供的預先定義範本開始著手。
   • 腳本必須包含一個 main 函數。
   • 指令碼必須使用 SDK end 函式，將布林結果傳回條件。
   • 在 IDE 中，邏輯運算子只能使用 SDK 方法的子集：
   • logical_operator.extract_param("ParamName"): 用於檢索輸入值。
   • logical_operator.LOGGER: 用於寫入偵錯日誌。
   • logical_operator.end(result): 結果為布林值（true 或 false）。

您可以直接在 IDE 中測試自訂邏輯運算子的邏輯。您可以輸入引數的測試值，並根據定義的條件，驗證函式是否傳回正確的布林值 (True 或 False) 結果。

參數

自訂邏輯運算子接受兩個參數：左側（必填且不可編輯）和右側（可選；可由使用者停用）。

• 範例 1： if [left side] not in [right side]
• 範例 2: if [left side] is greater than 80（無右側）。

逾時

• 預設逾時: 1 分鐘。
• 最大逾時時間: 3 分鐘。

注意： 由於平台會等待函數完成，因此您必須盡量縮短執行時間。最佳實踐是專注於直接資料轉換，避免查詢外部資料來源或執行繁重的處理。

在應對手冊中使用

自訂邏輯運算子會顯示在「應對手冊條件」、「先前動作條件」和「實體選取」的運算子選單中。

除了標準運算子（例如“等於”或“包含”）之外，還可以選擇自訂邏輯運算子。

處理錯誤

如果自訂邏輯運算子函數在執行過程中遇到錯誤，則使用該運算子的劇本條件或步驟將會失敗。Python 腳本傳回的錯誤訊息會顯示在 playbook 運行視圖中，以協助進行故障排除。

限制

• 觸發條件或網路鉤子不支援自訂轉換函式和邏輯運算子。

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