收集 GitGuardian Enterprise 日志

解析器版本：1.0

本文档介绍了如何配置 GitGuardian Enterprise 以使用 Webhook 将日志推送到 Google Security Operations。

GitGuardian Enterprise 是一款密钥检测和补救平台，可监控源代码库、CI/CD 流水线和开发者工作站，以发现泄露的凭据和敏感数据。它会在检测到 Secret 时提供实时提醒，并帮助安全团队管理突发事件补救工作流。

准备工作

请确保满足以下前提条件：

• Google SecOps 实例
• 具有“管理员”访问权限级别的 GitGuardian Enterprise 工作区
• 访问 Google Cloud 控制台（用于创建 API 密钥）
• GitGuardian Business 方案或更高级别（支持自定义 webhook）

在 Google SecOps 中创建 Webhook Feed

创建 Feed

1. 前往 SIEM 设置 > Feed。
2. 点击添加新 Feed。
3. 在下一页上，点击配置单个 Feed。
4. 在 Feed 名称字段中，输入 Feed 的名称（例如 GitGuardian Enterprise Incidents）。
5. 选择 Webhook 作为来源类型。
6. 选择 GitGuardian Enterprise 作为日志类型。
7. 点击下一步。

8. 为以下输入参数指定值：

   • 定界符（可选）：留空（每个网络钩子请求包含一个事件）
   • 资产命名空间：资产命名空间
   • 注入标签：要应用于此 Feed 中事件的标签

9. 点击下一步。

10. 在最终确定界面中查看新的新闻信息流配置，然后点击提交。

生成并保存密钥

创建 Feed 后，您必须生成用于身份验证的密钥：

1. 在 Feed 详情页面上，点击生成密钥。
2. 系统会显示一个对话框，其中包含密钥。

3. 复制并妥善保存密钥。

获取 Feed 端点网址

1. 前往该 Feed 的详细信息标签页。
2. 在端点信息部分，复制 Feed 端点网址。

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. 选择限制密钥。
   2. 在选择 API 下拉菜单中，搜索并选择 Google SecOps API（或 Chronicle API）。

3. 点击保存。

4. 从页面顶部的 API 密钥字段中复制 API 密钥值。

5. 安全地保存 API 密钥。

配置 GitGuardian Enterprise webhook

构建网络钩子网址

• 将 Google SecOps 端点网址和 API 密钥组合在一起：

  <ENDPOINT_URL>?key=<API_KEY>
  

  示例：

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

在 GitGuardian 中创建自定义网络钩子

对于个人工作区：

1. 登录 GitGuardian 信息中心。
2. 依次前往设置 > Workspace > 集成 > 目标 > 自定义 webhook。
3. 点击添加自定义 webhook 或创建新的自定义 webhook。

4. 提供以下配置详细信息：

   • 名称：输入一个描述性名称（例如 Google SecOps SIEM Integration）。
   • 网址：粘贴包含 API 密钥的完整端点网址（如上所示）。
   • 签名令牌：粘贴在 Google SecOps 中创建 Feed 时生成的密钥。
   • 自定义标头（可选）：除非您需要指定环境或服务标记，否则请留空。

5. 在事件订阅部分中，选择要发送到 Google SecOps 的事件：

   • 突发事件：
     • ☑ 检测到新突发事件
     • ☑ 检测到新事件
     • ☑ 突发事件已解决
     • ☑ 忽略了突发事件
     • ☑ 重新打开了突发事件
     • ☑ 突发事件回归
     • ☑ 突发事件已分配
     • ☑ 突发事件已重新分配
     • ☑ 突发事件未分配
     • ☑ 突发事件严重程度已更改
     • ☑ 突发事件有效性已更改
     • ☑ 已授予突发事件访问权限
     • ☑ 已撤消突发事件访问权限
     • ☑ 公开分享突发事件
     • ☑ 突发事件未公开分享
     • ☑ 已提交反馈
     • ☑ 突发事件有新评论

6. 点击创建或保存。

7. GitGuardian 会发送一条测试消息，以验证网络钩子是否正常运行。

对于企业工作区：

1. 登录 GitGuardian 信息中心。

2. 确定 webhook 的范围：

   • 对于工作区中的所有突发事件：前往所有突发事件团队。
   • 对于特定团队的突发事件：前往所需团队。

3. 依次前往设置 > Workspace > 集成 > 目标 > 自定义 webhook。

   • 或者，在团队页面中，依次前往 Integrations（集成）> Custom webhook（自定义 webhook）。

4. 点击添加自定义 webhook 或创建新的自定义 webhook。

5. 提供以下配置详细信息：

   • 名称：输入一个描述性名称（例如 Google SecOps SIEM Integration）。
   • 网址：粘贴包含 API 密钥的完整端点网址（如上所示）。
   • 签名令牌：粘贴在 Google SecOps 中创建 Feed 时生成的密钥。
   • 自定义标头（可选）：除非您需要指定环境或服务标记，否则请留空。

6. 在事件订阅部分中，选择要发送到 Google SecOps 的事件：

   • 突发事件：
     • ☑ 检测到新突发事件
     • ☑ 检测到新事件
     • ☑ 突发事件已解决
     • ☑ 忽略了突发事件
     • ☑ 重新打开了突发事件
     • ☑ 突发事件回归
     • ☑ 突发事件已分配
     • ☑ 突发事件已重新分配
     • ☑ 突发事件未分配
     • ☑ 突发事件严重程度已更改
     • ☑ 突发事件有效性已更改
     • ☑ 已授予突发事件访问权限
     • ☑ 已撤消突发事件访问权限
     • ☑ 公开分享突发事件
     • ☑ 突发事件未公开分享
     • ☑ 已提交反馈
     • ☑ 突发事件有新评论

7. 点击创建或保存。

8. GitGuardian 会发送一条测试消息，以验证网络钩子是否正常运行。

验证 webhook 传送

1. 在 GitGuardian 信息中心内，前往您的自定义 webhook 配置。
2. 点击发送测试消息或测试 Webhook。
3. GitGuardian 会向 Google SecOps 发送示例载荷。
4. 在 Google SecOps 控制台中，依次前往 SIEM 设置 > Feed。
5. 找到您的 GitGuardian Feed，并验证是否已收到测试事件。

6. 检查 Feed 状态是否显示为有效，并带有最近的提取时间戳。

身份验证方法参考

Google SecOps webhook Feed 支持多种身份验证方法。选择供应商支持的方法。

方法 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 事件。虽然网络钩子通常很可靠，但无法保证一定能送达。

对于关键用例，请考虑通过定期 API 轮询来补充 Webhook，以确保不会错过任何事件。

UDM 映射表

更新日志

查看此解析器的更新日志

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。