貢獻社群回應整合項目

支援：

本文說明如何透過社群貢獻，向 Google SecOps 提交回應整合項目。提交的所有整合項目都會經過 Google SecOps 官方團隊的審查程序，重點是本文件中強調的需求。

回應整合中繼資料

名稱

「名稱」應對應至整合項目要整合的產品名稱，且不得包含任何特殊字元。

顯示名稱應以空白字元分隔，例如 Vertex AI，而非 VertexAI。

整合 ID

整合 ID 是整合的專屬 ID。整合建立完成後，就無法變更這個值。ID 應與 Name 的值相同，但須移除空白字元。

您可以在平台的大多數位置找到 ID。

說明

「Description」應提供整合產品的概略總覽，且不得超過 500 個半形字元。必須包含下列資訊：

This integration is owned by the "{vendor name}". Support Contact: {email}.

避免在說明中加入網址。

標誌

每個整合項目都應提供 SVG 圖示。這個圖示應能配合平台內的主題調整。圖示只能沿用平台的

您應在下列頁面驗證標誌：

以下是符合樣式指南的 SVG 標誌範例：

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>

請務必先編碼 SVG，再將其新增至整合定義 檔案，如內容中心的其他整合項目所示。

在整合過程中，您可以新增連結，將使用者導向說明文件。這份文件應由您自行代管。

使用者可以從「Configure Instance」(設定執行個體) 對話方塊的「Parameters」(參數) 區段存取說明文件連結。

設定參數

除非基礎 API 不需要任何驗證，且 API 根目錄可以硬式編碼，否則所有整合都應包含設定參數 (API 根目錄 + 驗證參數)。對於所有需要驗證的整合，都應有 Verify SSL 參數。

所有參數都應附上說明。說明應協助使用者在平台內設定整合。請勿在參數說明中加入網址。

Ping 動作

Ping 動作是平台用來驗證 API 連線能力 的特殊動作。即使整合項目沒有其他動作，也必須執行這項動作。每當使用者按下整合設定中的「Test」按鈕時，系統應顯示準確的連線狀態。

版本資訊

發行說明的一般結構應遵循下列格式：

  • {integration item} - {update}
    • 例如：Get Case Details - Added ability to fetch information about affected IOCs

視情況而定，特定情境有專屬版本資訊：

  • 如果是新的整合：New Integration Added - {integration name}
  • 如果新增動作：New Action Added - {action name}
  • 如果新增連接器：New Connector Added - {connector name}
  • 如果新增工作：New Job Added - {job name}
  • 如果將預先定義的小工具新增至動作：{action name} - Added Predefined Widget.
  • 如果預先定義的小工具已更新：{action name} - Updated Predefined Widget.
  • 如要進行會影響所有整合項目的變更：Integration - {Update}
  • 如要變更所有動作：Integration's Actions - {Update}
  • 如要進行會影響所有連接器的變更：Integration's Connectors - {Update}
  • 如要變更所有工作：Integration's Jobs - {Update}

如果版本包含回歸變更，則必須在版本資訊中指定 REGRESSIVE!。例如： Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

版本資訊可在整合中的「詳細資料」按鈕隨即顯示的「整合詳細資料」側邊抽屜中查看。

版本管理

每次更新整合功能後，整合版本都應加 1。版本應以整數表示。不允許使用 11.1.3 或 11.1 等次要版本。

標記

您也可以視需要為整合服務新增標記。請避免建立新的標記類型，而是使用平台中已有的標記。如果找不到合適的標記，請洽詢審查團隊。

一般注意事項

  • 提交前請先測試所有整合內容。
  • 檢查所有整合內容，找出潛在安全漏洞和易受攻擊的依附元件。
  • 開發期間一律使用最新支援的 Python 版本 (Python 3.11)。

動作

名稱

動作的「名稱」應指向執行的活動，例如「取得案件詳細資料」、「列出實體事件」或「執行搜尋」。

如果動作主要用於處理實體，建議在名稱中加入 Entity，例如 Enrich Entities。

動作名稱應以 2 到 3 個字詞表示。

說明

動作的「說明」應向使用者強調執行動作的結果。

如果動作可搭配實體使用，則需要附加支援的實體類型相關資訊。例如：

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

如果動作在「非同步」模式下運作，則必須在說明中提供下列附註：

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

說明長度請盡量控制在 500 個半形字元以內。

動作參數

動作設定參數應有直覺易懂的名稱。請避免使用特殊字元，並盡量將動作參數名稱限制在 2 到 4 個字。

參數說明應向使用者解釋該參數對動作執行的影響。如果參數支援預先決定的支援值數量，請在說明中提供下列部分：Possible Values: {value 1}, {value 2}

動作輸出內容 (指令碼結果)

指令碼結果應代表動作的簡單結果。在大多數情況下，它應該只會指向名為 is_success 的變數，該變數可採用 true 或 false 值。

一般來說，如果動作已完成執行並執行作業，則 is_success 應為 true。

動作輸出內容 (JSON 結果)

JSON 結果是動作最重要的輸出內容。執行教戰手冊時，可以存取 JSON 結果中的所有資料。確認有效的 JSON 物件是否已推送至輸出內容。

JSON 結果的大小上限為 15 MB。

建構 JSON 結果時，請確保執行期間不會有任何專屬鍵。舉例來說，下列 JSON 物件代表結構不良，因為無法在劇本中使用：


{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}

請改為使用以下格式：


[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]

如果您在動作中使用實體，並傳回每個實體的結果，建議您按照下列方式建構 JSON 結果：


[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]

請務必考量動作的輸出內容在自動化程序中的用途。

確認動作有 JSON 範例。

平台會在建構劇本時，於運算式建構工具中使用 JSON 範例。準確的 JSON 範例可大幅提升劇本建構體驗。從 JSON 範例中移除所有 PII 資訊。

動作輸出內容 (實體擴充)

如果動作是在實體上執行，您可以在執行動作期間，為實體附加額外的中繼資料。該中繼資料的結構應符合以下格式：{integration identifier}_{key}。例如：WebRisk_is_malicious。

您可以在實體詳細資料頁面中找到新增的中繼資料。

動作輸出內容 (輸出訊息)

輸出訊息應以更具描述性的方式，向使用者說明動作執行情況。應向使用者指出動作執行的結果。

如果部分實體成功完成擴充，但其他實體沒有，最佳做法是在訊息中提供每個實體的狀態資訊。

如果認為執行動作時發生重大錯誤，請確保有針對這種情況的詳細訊息，並讓動作失敗。如果動作失敗，對應的應對手冊會停止執行，直到錯誤解決或手動略過為止。

輸出訊息範例：

  • Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
  • Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
  • None of the provided entities were found in VirusTotal.
  • Successfully executed query "{query}" in Google SecOps.

如果動作應失敗並停止執行應對手冊，建議採用下列結構的輸出訊息：

"Error executing action "{action name}". Reason: {error}'

請避免提供完整的錯誤追蹤記錄。請改用自然語言向使用者說明實際問題。

連接器

名稱

連接器的名稱應引導使用者前往要擷取的資料。一般來說，名稱的結構應如下所示：

  • {integration display name} - {data that is being ingested} Connector
    • 例如：Crowdstrike - Pull Alerts Connector

說明

連接器的「說明」應向使用者強調連接器會擷取哪些內容，例如 Pull alerts from Crowdstrike。此外，您必須提供動態清單支援的相關資訊，例如 Dynamic List works with the display_name parameter.

在這個情況下，最終說明會如下所示：

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

說明長度請盡量控制在 500 個半形字元以內。

連接器參數

連接器設定參數應使用直覺式名稱。 請避免使用特殊字元，並盡量將動作參數名稱限制在 2 到 4 個字。

參數說明應向使用者解釋該參數對連接器執行的影響。

如果參數支援預先決定的支援值數量，請在說明中提供下列章節：Possible Values: {value 1}, {value 2}。應包含下列參數：

  • 要擷取的快訊數量上限：決定在 1 次連接器疊代期間應處理的 {object} 數量。
  • 最多回溯 {小時/天}：決定連接器第一次疊代時的開始時間。舉例來說，如果「Max Hours Backwards」(最長回溯時數) 設為 1，連接器就會開始從一小時前提取資料。
  • 驗證 SSL：驗證與 API/執行個體的連線。

本體對應

建議為每個建立的連接器提供本體對應，確保共同客戶能享有最佳體驗。

本體對應功能可用於自動建立實體 (IOC 和資產)。此外，系統欄位的重要中繼資料 (例如「開始時間」和「結束時間」) 也是在此定義。

動態清單

動態清單是選用功能，可讓您建立用於擷取的進階篩選器。您可以靈活運用這項功能建構任何自訂邏輯，同時享有獨特的 UX。最常見的用途是定義允許或封鎖的擷取清單。

如果您要為動態清單建構任何自訂邏輯，請務必在連接器的說明中提供。此外，建議您加入「Use Dynamic List as a blocklist」參數，以便支援反向邏輯。

工作

名稱

作業的「名稱」應向使用者說明這項作業執行的內容。一般來說，名稱結構應如下所示：

  • {integration display name} - {process} Job
    • 例如：ServiceNow - Sync Incidents Job

說明

職務說明應向使用者強調職務在疊代期間的職責；例如 This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

說明長度盡量不要超過 500 個字元。

工作參數

工作設定參數應使用直覺式名稱。請避免使用特殊字元，並盡量將動作參數名稱限制在 2 到 4 個字。

參數說明應向使用者解釋該參數對工作執行的影響。

如果參數支援預先決定的支援值數量，請在說明中提供下列部分：

Possible Values: {value 1}, {value 2}。

除了驗證參數外，所有工作都應包含下列參數：

  • 最多可回溯 {小時/天}：決定作業第一次疊代的開始時間。
  • 驗證 SSL：驗證與 API/執行個體的連線。

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