审计事件流

  • 引入于 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

引入于 14.9 版本

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

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

使用 API

至少具有群组所有者角色的用户可以随时使用 externalAuditEventDestinations 查询类,查看事件流目的地列表。

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

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

删除流目的地

至少具有群组所有者角色的用户可以使用 deleteAuditEventDestinations mutation 类,删除事件流目的地。

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

使用 GitLab UI

引入于 14.9 版本

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

  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。默认禁用。

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

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

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

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

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

Headers

Headers 的格式如下:

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 版本。

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

Headers

Headers 的格式如下:

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
}