收集 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 配置，然后点击提交。

生成并保存密钥

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

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

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

获取 Feed 端点网址

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

  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. 选择限制密钥。
    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://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 Feed 创建过程中获得的密钥。
    • 自定义标头（可选）：除非您需要指定环境或服务标记，否则请留空。

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

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

  6. 点击创建或保存。

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

对于企业工作区：

  1. 登录 GitGuardian 信息中心。

  2. 确定 webhook 的范围：

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

  3. 依次前往设置 > 工作区 > 集成 > 目的地 > 自定义 Webhook。

    • 或者，您也可以从团队页面中依次前往集成 > 自定义 Webhook。

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

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

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

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

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

  7. 点击创建或保存。

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

验证 webhook 传送

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

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

身份验证方法参考

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

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 标头的值
    • 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（每秒查询次数） 15000
请求超时 30 秒
重试行为 自动（使用指数退避算法）

最佳做法

  • 选择事件：仅订阅与安全运营相关的事件，以减少干扰。
  • 团队范围：对于企业工作区，可以在团队级别创建 Webhook，以按团队所有权过滤突发事件。
  • 签名验证：安全地存储签名令牌，切勿将其提交到源代码。
  • 监控：定期在 GitGuardian 信息中心内检查 Webhook 传送状态。
  • 测试：在投入生产环境之前，使用测试消息功能验证网络钩子配置。

送达保证

重要提示：Webhook 传送是尽最大努力完成的，无法保证一定能成功。如果 Google SecOps 端点无法访问或存在网络问题，则可能无法接收网络钩子事件。虽然 Webhook 通常是可靠的，但无法保证一定能成功传送。

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

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 专业人士的解答。