收集 GitGuardian Enterprise 記錄

剖析器版本：1.0

本文說明如何設定 GitGuardian Enterprise，透過 Webhook 將記錄檔推送至 Google Security Operations。

GitGuardian Enterprise 是一個機密偵測和修復平台，可監控原始碼存放區、CI/CD pipeline 和開發人員工作站，找出外洩的憑證和機密資料。偵測到 Secret 時，這項服務會提供即時警示，協助資安團隊管理事件修復工作流程。

事前準備

請確認您已完成下列事前準備事項：

• Google SecOps 執行個體
• 具備管理員存取層級的 GitGuardian Enterprise 工作區
• Google Cloud 控制台存取權 (用於建立 API 金鑰)
• GitGuardian Business 方案或更高級別 (支援自訂 Webhook)

在 Google SecOps 中建立 Webhook 動態饋給

建立動態饋給

1. 依序前往 「SIEM 設定」 > 「動態饋給」。
2. 按一下「新增動態消息」。
3. 在下一頁，點按「設定單一動態饋給」。
4. 在「Feed name」(動態饋給名稱) 欄位中，輸入動態饋給名稱 (例如 GitGuardian Enterprise Incidents)。
5. 選取「Webhook」做為「來源類型」。
6. 選取「GitGuardian Enterprise」做為「記錄類型」。
7. 點選「下一步」。

8. 指定下列輸入參數的值：

   • 分割分隔符 (選用)：留空 (每個 Webhook 要求包含單一事件)
   • 資產命名空間：資產命名空間
   • 擷取標籤：要套用至這個動態饋給事件的標籤

9. 點選「下一步」。

10. 在「Finalize」(完成) 畫面中檢查新的新聞動態消息設定，然後按一下「Submit」(提交)。

產生並儲存密鑰

建立動態饋給後，您必須產生用於驗證的密鑰：

1. 在動態饋給詳細資料頁面，按一下「產生 Secret Key」。
2. 對話方塊會顯示密鑰。

3. 複製並妥善儲存密鑰。

取得動態饋給端點網址

1. 前往動態饋給的「詳細資料」分頁。
2. 在「端點資訊」部分，複製「動態消息端點網址」。

3. 網址格式為：

   https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import
   

   其中 {region} 是 Google SecOps 執行個體的區域 (例如 us、europe 或 asia-southeast1)，{parent} 是資源路徑，格式為 projects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE>。

4. 請儲存這個網址，以利進行後續步驟。

5. 按一下「完成」。

建立 Google Cloud API 金鑰

Google SecOps 需要 API 金鑰才能進行驗證。在 Google Cloud 控制台中建立受限制的 API 金鑰。

建立 API 金鑰

1. 前往 Google Cloud 控制台的「憑證」頁面。
2. 選取專案 (與 Google SecOps 執行個體相關聯的專案)。
3. 依序點選「建立憑證」 > 「API 金鑰」。
4. 系統會建立 API 金鑰，並在對話方塊中顯示。
5. 按一下「編輯 API 金鑰」，即可限制金鑰。

限制 API 金鑰

1. 在「API 金鑰」設定頁面中：

   • 名稱：輸入描述性名稱 (例如 Google SecOps GitGuardian Webhook API Key)

2. 在「API 限制」下方：

   1. 選取「Restrict key」(限制金鑰)。
   2. 在「選取 API」下拉式選單中，搜尋並選取「Google SecOps API」 (或「Chronicle API」)。

3. 按一下 [儲存]。

4. 複製頁面頂端「API 金鑰」欄位中的 API 金鑰值。

5. 妥善保存 API 金鑰。

設定 GitGuardian Enterprise Webhook

建構 Webhook 網址

• 合併 Google SecOps 端點網址和 API 金鑰：

  <ENDPOINT_URL>?key=<API_KEY>
  

  範例：

  https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
  

在 GitGuardian 建立自訂 Webhook

個人工作區：

1. 登入 GitGuardian 資訊主頁。
2. 依序前往「設定」 >「Workspace」 >「整合」 >「目的地」 >「自訂 Webhook」。
3. 按一下「新增自訂 Webhook」或「建立新的自訂 Webhook」。

4. 提供下列設定詳細資料：

   • 名稱：輸入描述性名稱 (例如 Google SecOps SIEM Integration)。
   • 網址：貼上完整的端點網址和 API 金鑰。
   • Signature token：貼上建立 Google SecOps 動態饋給時產生的 Secret Key。
   • 自訂標頭 (選用)：除非需要指定環境或服務標記，否則請留空。

5. 在「Event Subscription」(事件訂閱) 部分，選取要傳送至 Google SecOps 的事件：

   • 事件：
     • ☑ 偵測到新事件
     • ☑ 偵測到新事件
     • ☑ 事件已解決
     • ☑ 忽略事件
     • ☑ 事件重新開啟
     • ☑ 事件迴歸
     • ☑ 指派事件
     • ☑ 事件已重新指派
     • ☑ 事件未指派
     • ☑ 事件嚴重性已變更
     • ☑ 事件有效性已變更
     • ☑ 已授予事件存取權
     • ☑ 事件存取權已撤銷
     • ☑ 公開分享事件
     • ☑ 事件未公開分享
     • ☑ 已提交意見回饋
     • ☑ 事件有新留言

6. 按一下「建立」或「儲存」。

7. GitGuardian 會傳送測試訊息，確認 Webhook 運作正常。

企業工作區：

1. 登入 GitGuardian 資訊主頁。

2. 決定 Webhook 的範圍：

   • 工作區中的所有事件：前往「All-incidents team」。
   • 特定團隊事件：前往所需團隊。

3. 依序前往「設定」 >「Workspace」 >「整合」 >「目的地」 >「自訂 Webhook」。

   • 或者，您也可以在團隊頁面中，依序前往「整合」>「自訂 Webhook」。

4. 按一下「新增自訂 Webhook」或「建立新的自訂 Webhook」。

5. 提供下列設定詳細資料：

   • 名稱：輸入描述性名稱 (例如 Google SecOps SIEM Integration)。
   • 網址：貼上完整的端點網址和 API 金鑰。
   • Signature token：貼上建立 Google SecOps 動態饋給時產生的 Secret Key。
   • 自訂標頭 (選用)：除非需要指定環境或服務標記，否則請留空。

6. 在「Event Subscription」(事件訂閱) 部分，選取要傳送至 Google SecOps 的事件：

   • 事件：
     • ☑ 偵測到新事件
     • ☑ 偵測到新事件
     • ☑ 事件已解決
     • ☑ 忽略事件
     • ☑ 事件重新開啟
     • ☑ 事件迴歸
     • ☑ 指派事件
     • ☑ 事件已重新指派
     • ☑ 事件未指派
     • ☑ 事件嚴重性已變更
     • ☑ 事件有效性已變更
     • ☑ 已授予事件存取權
     • ☑ 事件存取權已撤銷
     • ☑ 公開分享事件
     • ☑ 事件未公開分享
     • ☑ 已提交意見回饋
     • ☑ 事件有新留言

7. 按一下「建立」或「儲存」。

8. GitGuardian 會傳送測試訊息，確認 Webhook 是否正常運作。

驗證 Webhook 傳送

1. 在 GitGuardian 資訊主頁中，前往自訂 Webhook 設定。
2. 按一下「傳送測試訊息」或「測試 Webhook」。
3. GitGuardian 會將範例酬載傳送至 Google SecOps。
4. 在 Google SecOps 控制台中，依序前往 「SIEM Settings」(SIEM 設定) >「Feeds」(動態饋給)。
5. 找到 GitGuardian 動態饋給，確認已收到測試事件。

6. 確認「動態饋給狀態」顯示「有效」，且有最近的擷取時間戳記。

驗證方式參考資料

Google SecOps Webhook 摘要支援多種驗證方式。請選擇供應商支援的方法。

方法 1：查詢參數 (建議用於 GitGuardian)

GitGuardian 自訂 Webhook 搭配附加至網址的憑證使用時，效果最佳。

• 網址格式：

  <ENDPOINT_URL>?key=<API_KEY>
  

  範例：

  https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
  

  GitGuardian Webhook 設定：

  • 網址：包含 API 金鑰參數的完整端點網址
  • 簽章權杖：Google SecOps 密鑰 (用於 HMAC 驗證)

• 要求格式：

  POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
  Content-Type: application/json
  Timestamp: 1234567890
  Gitguardian-Signature: sha256=abc123...
  
  {
      "source": "GitGuardian",
      "timestamp": "2025-01-15T10:30:00Z",
      "action": "incident_triggered",
      "incident": {...}
  }
  

方法 2：自訂標頭 (替代方法)

如要避免在網址中加入憑證，請使用自訂標頭。

• 要求格式：

  POST <ENDPOINT_URL> HTTP/1.1
  Content-Type: application/json
  x-goog-chronicle-auth: <API_KEY>
  Timestamp: 1234567890
  Gitguardian-Signature: sha256=abc123...
  
  {
      "source": "GitGuardian",
      "timestamp": "2025-01-15T10:30:00Z",
      "action": "incident_triggered",
      "incident": {...}
  }
  

GitGuardian Webhook 簽章驗證

GitGuardian 會使用 HMAC-SHA256 簽署所有 Webhook 酬載，確保真實性並防止竄改。

簽章標頭

GitGuardian 在 Webhook 要求中包含下列標頭：

• Gitguardian-Signature：HMAC-SHA256 簽章，格式為 sha256=<hex_digest>
• 時間戳記：傳送要求時的 UNIX 時間戳記
• X-GitGuardian-Signature：已淘汰的標頭 (仍支援回溯相容性)

簽名演算法

• 簽章的計算方式如下：

  HMAC-SHA256(key=timestamp + signature_token, message=payload)
  

  其中：

  • timestamp：Timestamp 標頭的值
  • signature_token：在 GitGuardian Webhook 設定中設定的密鑰
  • payload：原始 JSON 要求主體，以 UTF-8 字串表示

驗證範例 (Python)

import hmac
import hashlib

def verify_signature(signature: str, timestamp: str, signature_token: str, payload: str) -> bool:
    if not signature.startswith("sha256="):
        return False
    
    signature = signature.split("sha256=")[-1]
    
    hmac_digest = hmac.new(
        key=bytes(timestamp + signature_token, "utf-8"),
        msg=bytes(payload, "utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, hmac_digest)

重送攻擊防護

• Timestamp 標頭可防範重送攻擊。如果目前時間戳記與 Webhook 時間戳記相差超過幾秒 (建議：300 秒)，請拒絕要求。

事件類型和酬載結構

GitGuardian 會根據事件生命週期變化，傳送不同的事件類型。

事件

酬載結構範例

• 所有 Webhook 酬載都遵循以下結構：

  {
      "source": "GitGuardian",
      "timestamp": "2025-01-15T10:30:00.123456Z",
      "action": "incident_triggered",
      "message": "A new incident has been detected.",
      "target_user": "john.doe@example.com",
      "target_team": "Security Team",
      "custom_webhook_name": "Google SecOps SIEM Integration",
      "incident": {
          "id": 12345,
          "date": "2025-01-15T10:29:58.123456Z",
          "detector": {
              "name": "aws_iam",
              "display_name": "AWS Keys",
              "nature": "specific",
              "family": "credentials"
          },
          "secret_hash": "abc123...",
          "secret_revoked": false,
          "validity": "valid",
          "occurrence_count": 1,
          "status": "triggered",
          "assignee_email": null,
          "severity": "high",
          "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345"
      }
  }
  

Webhook 限制和最佳做法

要求限制

最佳做法

• 事件選取：只訂閱與資安營運相關的事件，減少不必要的資訊。
• 團隊範圍：如果是企業工作區，請在團隊層級建立 Webhook，依團隊擁有權篩選事件。
• 簽章驗證：安全地儲存簽章權杖，切勿將其提交至原始碼。
• 監控：定期在 GitGuardian 資訊主頁查看 Webhook 傳送狀態。
• 測試：在正式環境使用前，請先透過測試訊息功能驗證 Webhook 設定。

關於通知訊息的注意事項

重要事項：系統會盡力傳送 Webhook，但不保證一定會成功。如果無法連上 Google SecOps 端點，或發生網路問題，可能就無法接收 Webhook 事件。雖然 Webhook 通常很可靠，但我們無法保證一定會傳送通知。

對於重要用途，請考慮定期輪詢 API，確保不會錯過任何事件。

UDM 對應表

變更記錄

查看這個剖析器的變更記錄

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