收集 GitGuardian Enterprise 記錄

剖析器版本：1.0

支援的國家/地區：

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

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

事前準備

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

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

在 Google SecOps 中建立 Webhook 動態饋給

建立動態饋給

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

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

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

  9. 點選「下一步」。

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

產生並儲存密鑰

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

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

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

取得動態消息端點網址

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

  3. 網址格式為：

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

    或

    https://<REGION>-malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

  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 key」(API 金鑰) 欄位複製 API 金鑰值。

  5. 安全地儲存 API 金鑰。

設定 GitGuardian Enterprise Webhook

建構 Webhook 網址

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

    <ENDPOINT_URL>?key=<API_KEY>

    範例：

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...

在 GitGuardian 中建立自訂 Webhook

個人工作區：

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

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

    • 名稱：輸入描述性名稱 (例如 Google SecOps SIEM Integration)。
    • 網址：貼上上述包含 API 金鑰的完整端點網址。
    • 簽章權杖：貼上從 Google SecOps 動態饋給建立作業取得的密鑰。
    • 自訂標頭 (選填)：除非需要指定環境或服務標記，否則請留空。

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

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

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

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

商用工作區：

  1. 登入 GitGuardian 資訊主頁。

  2. 判斷 Webhook 的範圍：

    • 如要查看工作區中的所有事件，請前往「All-incidents team」(所有事件團隊)。
    • 如要查看特定團隊事件：請前往所需團隊。

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

    • 或者，從團隊頁面依序前往「整合」>「自訂 Webhook」。

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

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

    • 名稱：輸入描述性名稱 (例如 Google SecOps SIEM Integration)。
    • 網址：貼上上述包含 API 金鑰的完整端點網址。
    • 簽章權杖：貼上從 Google SecOps 動態饋給建立作業取得的密鑰。
    • 自訂標頭 (選填)：除非需要指定環境或服務標記，否則請留空。

  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 網頁掛鉤動態消息支援多種驗證方法。選擇供應商支援的方法。

GitGuardian 自訂 Webhook 最適合搭配附加至網址的憑證。

  • 網址格式：

    <ENDPOINT_URL>?key=<API_KEY>

    範例：

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?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 會根據事件生命週期變化傳送不同類型的事件。

事件

事件類型 動作值 說明
偵測到新事件 incident_triggered 偵測到新的機密事件
偵測到新事件 new_occurrence 發現現有事件的新發生次數
事件已解決 incident_resolved 事件已標示為已解決
事件已忽略 incident_ignored 事件已標示為忽略
事件已重啟 incident_reopened 先前已結案的事件已重新開啟
事件迴歸 incident_regression 這個事件發現新的迴歸問題
事件已指派 incident_assigned 事件已指派給使用者
事件已重新指派 incident_reassigned 事件已重新指派給其他使用者
事件已取消指派 incident_unassigned 系統已取消指派使用者處理這起事件
嚴重性已變更 incident_severity_changed 嚴重程度已更新
有效性已變更 incident_validity_changed 有效性狀態已更新
已授予存取權 incident_access_granted 使用者已獲授權可存取這起事件
存取權已撤銷 incident_access_revoked 已撤銷使用者對這起事件的存取權
公開分享 incident_shared_publicly 已產生公開分享連結
未公開分享 incident_unshared_publicly 公開分享連結已停用
已提交意見 issue_feedback_received 已提交這個事件的意見回饋
新留言 incident_note_created 已為這個事件建立新記事

酬載結構範例

  • 所有 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 限制和最佳做法

要求限制

限制 值
要求大小上限 4 MB
每秒查詢次數 (QPS) 上限 15,000
要求逾時 30 秒
重試行為 自動執行指數輪詢

最佳做法

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

關於通知訊息的注意事項

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

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

UDM 對應表

記錄欄位 UDM 對應 邏輯
日期 metadata.event_timestamp 以 ISO8601 格式轉換
has_user metadata.event_type 如果 has_user 為 true，則設為「USER_UNCATEGORIZED」，否則設為「GENERIC_EVENT」
event_name metadata.product_event_type 直接複製值
id metadata.product_log_id 直接複製值
metadata.product_name 設為「GitGuardian Enterprise」
metadata.vendor_name 設為「GitGuardian」
member_email principal.user.email_addresses 已從 member_email 合併
member_name principal.user.user_display_name 直接複製值
member_id principal.user.userid 已轉換為字串
action_type security_result.action_details 直接複製值
target_ids target.resource.product_object_id target_ids 第一個元素的值

變更記錄

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

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