回應整合社群貢獻指南
本文件說明透過社群貢獻向 Google SecOps 提交回應整合項目的規範。提交的所有整合項目都會經過 Google SecOps 官方團隊的審查程序，重點是本文件中強調的要求。
回應整合中繼資料
名稱
「名稱」應對應至整合功能要整合的產品名稱，且不得包含任何特殊字元。
顯示名稱應以空白字元分隔，例如「Vertex AI」，而非「VertexAI」。
整合 ID
整合 ID 是整合的專屬 ID。整合建立完成後，就無法變更這個值。ID 應與 Name 的值相同，但要移除空白字元。
平台上的大多數位置都會顯示 ID。
說明
說明應提供整合建立的產品總體概覽，且不得超過 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 連線的特殊動作。即使整合服務沒有其他動作，也必須採取這項行動。每當使用者按下整合設定中的「測試」按鈕，系統應顯示連線的準確狀態。
版本資訊
發行說明的一般結構應採用下列格式：
{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.
如果動作在 Async 模式下運作，則必須在說明中提供下列附註：
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}。
除了驗證參數外，所有工作都應包含下列參數：
- 「Max {Hours/Days} Backwards」(最長回溯 {小時/天} 數)：決定工作第一次疊代的開始時間。
- 驗證 SSL：驗證與 API/執行個體的連線。
還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。