审计事件流

  • 引入于 14.5 版本，功能标志名为 ff_external_audit_events_namespace，默认禁用。
  • 于 14.7 版本适用于 SaaS，在私有化部署版上默认启用。
  • 功能标志 ff_external_audit_events_namespace 移除于 14.8 版本。

事件流允许顶级群组的所有者设置 HTTP 端点，接收关于群组、子组和项目的所有审计事件，数据形式为结构化 JSON。

顶级群组所有者可以使用 Splunk HTTP Event Collector，在 Splunk 等第三方系统中管理其审计日志。任何可以接收结构化 JSON 数据的服务都可以用作端点。

note系统可以多次将单个事件流传输到同一目的地。使用有效负载中的 id 键，针对传入数据进行重复数据删除。

添加新的事件流目的地

caution事件流目的地将接收所有审计事件数据，其中可能包括敏感信息，确保您信任目标端点。

使用 GitLab UI 添加事件流目的地

至少具有群组所有者角色的用户可以为其添加事件流目的地：

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的群组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件
  3. 在主区域，选择 事件流 选项卡。
    • 当目的地列表为空时，选择 添加事件流 激活编辑模式并添加新目的地。
    • 当目的地列表不为空时，选择 事件流 选项卡下的 激活编辑模式。
  4. 输入您要添加的端点并选择 添加。

在以下情况下启用事件流：

  • 不显示警告。
  • 添加的端点显示在 UI 中。

使用 API 添加事件流目的地

要启用事件流，群组所有者必须使用 GraphQL API 中的 externalAuditEventDestinationCreate mutation 添加新的事件流目的地。 

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", groupPath: "my-group" } ) {
    errors
    externalAuditEventDestination {
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

以下情况，将启用事件流：

  • 返回的 errors 对象为空。
  • API 响应 200 OK。

列出当前启用的流目的地

使用 GitLab UI 列出当前启用的流目的地

至少具有群组所有者角色的用户可以列出事件流目的地：

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件
  3. 在主区域，选择 事件流 选项卡。

使用 API 列出当前启用的流目的地

群组所有者可以随时使用 ` externalAuditEventDesinations` 查询类，查看事件流目的地列表。 

query {
  group(fullPath: "my-group") {
    id
    externalAuditEventDestinations {
      nodes {
        destinationUrl
        verificationToken
        id
      }
    }
  }
}

如果结果列表为空，则不会为该群组启用审计事件流。

删除当前启用的流目的地

群组所有者可以随时使用 deleteAuditEventDestinations mutation 类型删除事件流目的地。

使用 GitLab UI 删除当前启用的事件流

群组的所有者角色可以删除事件流目的地。

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件。
  3. 在主区域，选择 事件流 选项卡。
  4. 选择每一项右侧的 。

外部流目的地在以下情况下被删除：

  • 不显示警告。
  • 删除的端点不显示在 UI 中。

使用 API 删除当前启用的事件流

您可以通过指定 ID 来删除事件流目的地。通过列出事件流目的地的详细信息获取所需的 ID。 


mutation{ 
  externalAuditEventDestinationDestroy(input: { id: destination }) {
    errors
  }
}

在以下情况下删除目的地：

  • 返回的 errors 对象为空。
  • API 响应为 200 OK。

成功删除最后一个目的地后，将为该群组禁用事件流。

验证事件真实性

引入于 14.8 版本。

每个流目的地都有唯一的验证令牌（verificationToken），可用于验证事件的真实性。此令牌是在创建事件目的地时生成的，并且无法更改。

每个流事件都包含一个随机的字母数字标识符，用于 X-Gitlab-Event-Streaming-Token HTTP header，当列出流目的地时，可以根据目的地的值进行验证。

Git 操作的审计事件流

引入于 14.9 版本，功能标志名为 audit_event_streaming_git_operations。默认禁用。

FLAG: 在私有化部署版，此功能默认不可用。要启用，请询问管理员启用功能标志 audit_event_streaming_git_operations。在 SaaS 上，此功能不可用。

当登录用户推送或拉取项目的远程 Git 仓库时，可以发送审计事件流：

  • 使用 SSH。
  • 使用 HTTP 或 HTTPS。
  • 在 GitLab UI 中使用 下载 按钮 ()。

对于未登录的用户，不会捕获审计事件。例如，在下载公开项目时。

要为 Git 操作配置审计事件流，请参阅添加新的事件流目的地。

请求头

请求头的格式如下： 

POST /logs HTTP/1.1
Host: <DESTINATION_HOST>
Content-Type: application/x-www-form-urlencoded
X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN>

SSH 事件的示例响应

抓取： 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "Administrator",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": {
      "protocol": "ssh",
      "action": "git-upload-pack"
    },
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "Administrator",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-02-23T06:21:05.283Z",
  "target_type": "Project",
  "target_id": 29
}

推送： 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "Administrator",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": {
      "protocol": "ssh",
      "action": "git-receive-pack"
    },
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "Administrator",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-02-23T06:23:08.746Z",
  "target_type": "Project",
  "target_id": 29
}

HTTP 和 HTTPS 事件的示例响应

抓取： 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "Administrator",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": {
      "protocol": "http",
      "action": "git-upload-pack"
    },
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "Administrator",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-02-23T06:25:43.938Z",
  "target_type": "Project",
  "target_id": 29
}

推送： 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "Administrator",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": {
      "protocol": "http",
      "action": "git-receive-pack"
    },
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "Administrator",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-02-23T06:26:29.294Z",
  "target_type": "Project",
  "target_id": 29
}

来自 GitLab UI 下载按钮的事件响应示例

抓取： 

{
  "id": 1,
  "author_id": 99,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "custom_message": "Repository Download Started",
    "author_name": "example_username",
    "target_id": 29,
    "target_type": "Project",
    "target_details": "example-group/example-project",
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "example_username",
  "entity_path": "example-group/example-project",
  "target_details": "example-group/example-project",
  "created_at": "2022-02-23T06:27:17.873Z",
  "target_type": "Project",
  "target_id": 29
}

合并请求批准操作的审计事件流

引入于 14.9 版本。

与项目内执行的合并批准操作相关的审计事件流。

请求头

请求头的格式如下： 

POST /logs HTTP/1.1
Host: <DESTINATION_HOST>
Content-Type: application/x-www-form-urlencoded
X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN>

示例请求体 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 6,
  "entity_type": "Project",
  "details": {
    "author_name": "example_username",
    "target_id": 20,
    "target_type": "MergeRequest",
    "target_details": "merge request title",
    "custom_message": "Approved merge request",
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "example_username",
  "entity_path": "example-group/example-project",
  "target_details": "merge request title",
  "created_at": "2022-03-09T06:53:11.181Z",
  "target_type": "MergeRequest",
  "target_id": 20
}