自訂轉換函式和邏輯運算子

支援的國家/地區：

Google SecOps SOAR

注意： 這項功能受《Google Security Operations 服務專屬條款》的《正式發布前產品條款》規範。正式發布前的功能或許只提供部分支援，而且這類功能的變更可能與其他正式發布前版本不相容。詳情請參閱《Google SecOps 技術支援服務指南》和《Google SecOps 服務專屬條款》。

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

擴充包

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

擴充功能套件的最佳做法

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

重要事項：在 IDE 中建立擴充功能套件時，需要所有環境的權限。

建立擴充功能套件

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

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

上傳依附元件

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

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

1. 在 IDE 中開啟 Extension Pack 設定。
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. 文件 (選用)：為運算式產生器定義產品內文件：
   • 預期輸入：說明函式預期接收的轉換器資料類型 (例如「字串」或「字串清單」)。
   • 預期輸出內容：說明函式預期會為這個轉換器傳回的資料類型 (例如「布林值」)。
   • 使用範例：提供如何叫用函式的範例 (例如 if_empty("new_value"))。

您可以在 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 指令碼傳回的錯誤訊息會顯示在劇本執行檢視畫面中，協助排解問題。

限制

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

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