收集 Atlassian Bitbucket 日志

解析器版本： 2.0

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

Atlassian Bitbucket 是一项基于 Git 的源代码库托管服务。它为开发团队提供代码协作、拉取请求工作流和 CI/CD 流水线。Bitbucket 支持云部署和自托管（数据中心）部署。

准备工作

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

• Google SecOps 实例
• Atlassian Bitbucket Cloud 或数据中心实例，且具有管理员访问权限
• 对 Google Cloud Console 的访问权限（用于创建 API 密钥）

在 Google SecOps 中创建 Webhook Feed

创建 Feed

1. 依次前往 SIEM 设置 > Feed。
2. 点击添加新 Feed 。
3. 在下一页上，点击配置单个 Feed 。
4. 在 Feed 名称 字段中，输入 Feed 的名称（例如 Bitbucket Webhook Logs）。
5. 选择 Webhook 作为来源类型 。
6. 选择 Atlassian Bitbucket 作为日志类型 。
7. 点击下一步 。
8. 为以下输入参数指定值：
   • 拆分定界符 （可选）：输入一个定界符来拆分多行事件。常见值：
     • \n - 换行符定界符（NDJSON 最常用的定界符）
     • 如果每个请求都包含单个事件，请留空
   • 资产命名空间：资产命名空间
   • 提取标签：要应用于此 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 Console 中创建受限 API 密钥。

创建 API 密钥

1. 前往 Google Cloud 控制台的凭据页面。
2. 选择您的项目（与您的 Google SecOps 实例关联的项目）。
3. 点击创建凭据 > API 密钥。
4. 系统会创建 API 密钥，并在对话框中显示。
5. 点击修改 API 密钥 以限制密钥。

限制 API 密钥

1. 在 API 密钥 设置页面中：
   • 名称：输入一个描述性名称（例如 Webhook API Key）
2. 在 API 限制 下：
   1. 选择限制密钥 。
   2. 在选择 API 下拉列表中，搜索并选择 Google SecOps API 。
3. 点击保存 。
4. 从页面顶部的 API 密钥 字段中复制 API 密钥值。

5. 妥善保存 API 密钥。

配置 Atlassian Bitbucket Webhook

构建网络钩子网址

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

  <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>
  

• 示例：

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

在 Bitbucket Cloud 中创建 Webhook

1. 以工作区或代码库管理员身份登录 Bitbucket Cloud 。
2. 前往要配置 Webhook 的代码库。
3. 依次前往代码库设置 > Webhook。
4. 点击 Add webhook 。
5. 提供以下配置详细信息：
   • 标题：输入一个描述性名称（例如 SIEM Webhook）。
   • 网址：粘贴包含 API 密钥和 Secret 的完整端点网址（如上所示）。
   • 状态：选择有效。
   • 触发器：选择从完整触发器列表中选择，然后选择要发送的事件：
     • 代码库：推送、派生、提交评论已创建
     • 拉取请求：已创建、已更新、已批准、未批准、已合并、已拒绝、评论已创建
     • 问题：已创建、已更新、评论已创建
6. 点击保存 。

在 Bitbucket 数据中心内创建 Webhook

1. 以项目或代码库管理员身份登录 Bitbucket 数据中心 。
2. 前往要配置 Webhook 的项目或代码库。
3. 依次前往项目设置 > Webhook （对于项目级）或代码库设置 > Webhook （对于代码库级）。
4. 点击创建 Webhook 。
5. 提供以下配置详细信息：
   • 名称：输入一个描述性名称（例如 SIEM Webhook）。
   • 网址：粘贴包含 API 密钥和 Secret 的完整端点网址（如上所示）。
   • 状态：选择有效。
   • 事件：选择要转发的事件：
     • 代码库：引用已更改、派生、评论已添加
     • 拉取请求：已打开、源分支已更新、已修改、审核者已更新、已批准、未批准、需要处理、已合并、已拒绝、已删除、评论已添加
6. 点击保存 。

验证 Webhook 传送

1. 创建 Webhook 后，在代码库中执行操作（例如推送提交）。
2. 依次前往代码库设置 > Webhook。
3. 点击 Webhook 旁边的查看请求 。
4. 验证请求是否显示 200 状态代码，以表明传送成功。

如需了解详情，请参阅 Bitbucket Cloud Webhook 文档 或 Bitbucket 数据中心 Webhook 文档。

身份验证方法参考

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

方法 1：自定义标头（推荐）

如果您的供应商支持自定义 HTTP 标头，请使用此方法以提高安全性。

• 请求格式：

  POST <ENDPOINT_URL> HTTP/1.1
  Content-Type: application/json
  x-goog-chronicle-auth: <API_KEY>
  x-chronicle-auth: <SECRET_KEY>
  
  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  

• 优点：

  • API 密钥和 Secret 在网址中不可见
  • 更安全（标头不会记录在 Web 服务器访问日志中）
  • 如果供应商支持，则首选此方法

方法 2：查询参数

如果您的供应商不支持自定义标头，请将凭据附加到网址。

• 网址格式：

  <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>
  

• 示例：

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

• 请求格式：

  POST <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY> HTTP/1.1
  Content-Type: application/json
  
  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  

缺点：

• 凭据在网址中可见
• 可能会记录在 Web 服务器访问日志中
• 安全性不如标头

方法 3：混合（网址 + 标头）

某些配置在网址中使用 API 密钥，在标头中使用密钥。

• 请求格式：

  POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
  Content-Type: application/json
  x-chronicle-auth: <SECRET_KEY>
  
  {
          "event": "data",
          "timestamp": "2025-01-15T10:30:00Z"
  }
  

身份验证标头名称

Google SecOps 接受以下标头名称进行身份验证：

对于 API 密钥：

• x-goog-chronicle-auth（推荐）
• X-Goog-Chronicle-Auth（不区分大小写）

对于密钥：

• x-chronicle-auth（推荐）
• X-Chronicle-Auth（不区分大小写）

Webhook 限制和最佳实践

请求限制

限制	值
最大请求大小	4 MB
最大 QPS（每秒查询次数）	15,000
请求超时	30 秒
重试行为	自动重试，并使用指数退避算法

UDM 映射表

日志字段	UDM 映射	逻辑
actor.display_name	principal.user.user_display_name	取自 actor.display_name 字段的值。
actor.nickname	principal.user.userid	取自 actor.nickname 字段的值。
actor.account_id	principal.user.product_object_id	取自 actor.account_id 字段的值。
actor.uuid	principal.user.product_object_id	当 actor.account_id 不存在时，取自 actor.uuid 字段的值。
actor.links.html.href	principal.url	取自 actor.links.html.href 字段的值。
repository.full_name	target.resource.name	取自 repository.full_name 字段的值。
repository.uuid	target.resource.product_object_id	取自 repository.uuid 字段的值。
repository.links.html.href	target.url	取自 repository.links.html.href 字段的值。
repository.project.key	target.resource.attribute.labels	以键值对的形式添加，键为“project_key”。
repository.project.name	target.resource.attribute.labels	以键值对的形式添加，键为“project_name”。
repository.workspace.slug	target.resource.attribute.labels	以键值对的形式添加，键为“workspace”。
push.changes[].new.name	target.resource.attribute.labels	以键值对的形式添加，键为“branch_name”。
push.changes[].new.target.hash	target.resource.attribute.labels	以键值对的形式添加，键为“commit_hash”。
push.changes[].new.target.message	target.resource.attribute.labels	以键值对的形式添加，键为“commit_message”。
push.changes[].new.target.date	target.resource.attribute.labels	以键值对的形式添加，键为“commit_date”。
push.changes[].new.target.author.raw	target.user.email_addresses	从作者原始字段中提取的电子邮件地址。
pullrequest.id	target.resource.attribute.labels	以键值对的形式添加，键为“pullrequest_id”。
pullrequest.title	target.resource.attribute.labels	以键值对的形式添加，键为“pullrequest_title”。
pullrequest.state	target.resource.attribute.labels	以键值对的形式添加，键为“pullrequest_state”。
pullrequest.author.display_name	target.user.user_display_name	取自 pullrequest.author.display_name 字段的值。
pullrequest.source.branch.name	target.resource.attribute.labels	以键值对的形式添加，键为“source_branch”。
pullrequest.destination.branch.name	target.resource.attribute.labels	以键值对的形式添加，键为“destination_branch”。
date	metadata.event_timestamp	解析为 ISO8601 时间戳。如果 Webhook 载荷中存在，则用作事件时间戳。
	metadata.event_type	最初设置为“GENERIC_EVENT”。根据事件键以及正文和目标字段是否存在，更改为“USER_RESOURCE_ACCESS”“USER_RESOURCE_UPDATE_CONTENT”或“USER_UNCATEGORIZED”。
	metadata.product_event_type	根据 X-Event-Key Webhook 标头值进行设置（例如 repo:push、pullrequest:created、pullrequest:updated）。
	metadata.product_name	设置为“Atlassian Bitbucket”。
	metadata.vendor_name	设置为“Atlassian”。

更新日志

查看此解析器的更新日志

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