审计事件流

  • 引入于 14.5 版本，功能标志名为 ff_external_audit_events_namespace，默认禁用。
  • 于 14.7 版本适用于 SaaS，在私有化部署版上默认启用。
  • 功能标志 ff_external_audit_events_namespace 移除于 14.8 版本。
  • 为了更好地服务中国企业用户，极狐GitLab 自 15.0 版本开始，将 Stream Audit Event 功能从旗舰版降入专业版。而 GitLab CE 与 EE 版本中，该功能依旧为旗舰版。
  • 子组事件记录引入于 15.2 版本。
  • 自定义 HTTP headers API 引入于 15.1 版本，功能标志为 streaming_audit_event_headers。默认禁用。
  • 自定义 HTTP headers API 在 SaaS 和私有化部署版上启用于 15.2 版本。
  • 自定义 HTTP headers API 一般可用于 15.3 版本。功能标志 streaming_audit_event_headers 已删除。
  • 自定义 HTTP headers UI 引入于 15.2 版本，功能标志 为 custom_headers_streaming_audit_events_ui。默认禁用。
  • 自定义 HTTP headers UI 一般可用于 15.3 版本。功能标志 custom_headers_streaming_audit_events_ui 已删除。
  • 提升用户体验于 15.3 版本。
  • 用户指定的验证令牌 API 支持引入于 15.4 版本。

用户可以为顶级群组设置流目的地，接收有关该群组、其中子组和项目的所有审计事件作为结构化 JSON。

顶级群组所有者可以在第三方系统中管理他们的审计日志。任何可以接收结构化 JSON 数据的服务都可以用作流目的地。

每个流目的地最多可以包含 20 个自定义 HTTP headers，其中包含每个流传输事件。

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

添加新的流目的地

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

使用 GitLab UI

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

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的群组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件
  3. 在主区域，选择 事件流 选项卡。
  4. 选择 添加流目的地，显示添加目的地的部分。
  5. 输入要添加的目的地 URL。
  6. 可选。找到 自定义 HTTP header 表。
  7. 忽略 启用 复选框，该复选框无效。
  8. 选择 添加 header，创建新的名称和值对。根据需要输入尽可能多的名称和值对。每个流式传输目标最多可以添加 20 个 headers。
  9. 填写完所有 headers 后，选择 添加，添加新的流目的地。

使用 API

要启用流并添加目的地，具有群组所有者角色的用户必须在 GraphQL API 中使用 externalAuditEventDestinationCreate mutation。 

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

群组所有者还可以选择使用 GraphQL auditEventsStreamingHeadersCreate mutation，指定他们自己的验证令牌（而不是默认的极狐GitLab 生成的）。验证令牌长度必须在 16 到 24 个字符之间，并且不修剪尾随空格。建议设置一个密码随机且唯一的值。例如： 

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

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

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

群组所有者可以使用 GraphQL auditEventsStreamingHeadersCreate mutation 添加 HTTP header。您可以通过列出所有流目的地，为群组或从上面的 mutation 中检索目的地 ID。 

mutation {
  auditEventsStreamingHeadersCreate(input: { destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/24601", key: "foo", value: "bar" }) {
    errors
  }
}

如果返回的 errors 对象为空，则创建 header。

列出流目的地

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

使用 UI

引入于 14.9 版本

列出流目的地：

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件
  3. 在主区域，选择 事件流 选项卡。
  4. 在项目的右侧，选择 编辑 ()，查看所有自定义 HTTP header。

使用 API

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

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

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

您需要此查询返回的 ID 值用于更新和删除 mutations。

更新流目的地

具有群组所有者角色的用户可以更新流目的地。

使用 UI

要更新流目的地自定义 HTTP header：

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的群组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件。
  3. 在主区域，选择 事件流 选项卡。
  4. 在项目的右侧，选择 编辑 ()。
  5. 找到 自定义 HTTP header 表。
  6. 找到您要更新的 header。
  7. 忽略 启用 复选框，该复选框无效。
  8. 选择 添加 header 创建新的名称和值对。根据需要输入尽可能多的名称和值对。每个流目的地最多可以添加 20 个标头。
  9. 选择 保存 更新流目的地。

使用 API

具有群组所有者角色的用户可以使用 auditEventsStreamingHeadersUpdate mutation 类型更新流目的地自定义 HTTP headers。您可以通过列出所有自定义 HTTP headers，来检索该群组的自定义 HTTP headers ID。 

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

在以下情况下，更新流目的地：

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

群组所有者可以使用 GraphQL auditEventsStreamingHeadersDestroy mutation 删除 HTTP header。您可以通过列出所有自定义 HTTP header，来检索群组的 header ID。 

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

如果返回的 errors 对象为空，则删除 header。

删除流目的地

具有群组所有者角色的用户可以删除流目的地。

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

使用 UI

删除事件流目的地：

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

要仅删除流目的地的自定义 HTTP headers：

  1. 在顶部栏上，选择 菜单 > 群组 并找到您的群组。
  2. 在左侧边栏中，选择 安全与合规 > 审计事件。
  3. 在主区域，选择 事件流 选项卡。
  4. 在项目的右侧，选择 编辑 ()。
  5. 找到 自定义 HTTP headers 表。
  6. 找到您要删除的 header。
  7. 在 header 右侧，选择 删除 ()。
  8. 选择 保存 更新流目的地。

使用 API

具有群组所有者角色的用户可以使用 externalAuditEventDestinationDestroy mutation 类型删除流目的地。您可以通过列出所有流目的地，来检索该群组的目的地 ID。 

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

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

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

群组所有者可以使用 GraphQL auditEventsStreamingHeadersDestroy mutation 删除 HTTP header。您可以通过列出所有自定义 HTTP headers，来检索群组的 header ID。 

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

如果返回的 errors 对象为空，则删除 header。

验证事件真实性

引入于 14.8 版本。

每个流目的地都有唯一的验证令牌（verificationToken），可用于验证事件的真实性。此令牌由所有者指定或在创建事件目的地时自动生成且无法更改。

每个流事件都在 X-Gitlab-Event-Streaming-Token HTTP header 中包含一个验证令牌，当列出流目的地时，可以根据目的地的值进行验证。

使用 UI

引入于 15.2 版本。

具有群组所有者角色的用户可以列出流目的地并查看验证令牌：

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

有效负载 schema

流式审计事件在响应正文中具有可预测的 schema。

字段 描述 备注
author_id 触发事件的用户的用户 ID  
author_name 触发事件的作者的可读名称 当作者不再存在时很有帮助
created_at 触发事件的时间戳  
details 包含附加元数据的 JSON 对象 没有定义的架构，但通常包含有关事件的附加信息
entity_id 审计事件实体的 ID  
entity_path 受可审计事件影响的实体的完整路径  
entity_type 实体类型的字符串表示 可接受的值包括 User、Group 和 Key 等。
event_type 审计事件类型的字符串表示  
id 审计事件的唯一标识符 如果需要，可用于重复数据删除
ip_address 用于触发事件的主机 IP 地址  
target_details 有关目标的其他详细信息  
target_id 审计事件目标的 ID  
target_type 目标类型的字符串表示  

Git 操作的审计事件流

  • 引入于 14.9 版本，功能标志名为 audit_event_streaming_git_operations。默认禁用。
  • 在 SaaS 上启用于 15.0 版本。
  • 在私有化部署版上默认启用于 15.1 版本。
  • details.author_class 字段添加于 15.3 版本。
在私有化部署版，此功能默认可用。要隐藏此功能，请询问管理员禁用功能标志 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",
    "author_class": "User",
    "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",
    "author_class": "User",
    "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
}

使用部署密钥的 SSH 事件的示例负载

引入于 15.3 版本。

抓取： 

{
  "id": 1,
  "author_id": -3,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "deploy-key-name",
    "author_class": "DeployKey",
    "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": "deploy-key-name",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-07-26T05:43:53.662Z",
  "target_type": "Project",
  "target_id": 29,
  "event_type": "repository_git_operation"
}

HTTP 和 HTTPS 事件的示例负载

抓取： 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "author_name": "Administrator",
    "author_class": "User",
    "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",
    "author_class": "User",
    "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
}

带有部署令牌的 HTTP 和 HTTPS 事件的示例负载

抓取： 

{
  "id": 1,
  "author_id": -2,
  "entity_id": 22,
  "entity_type": "Project",
  "details": {
    "author_name": "deploy-token-name",
    "author_class": "DeployToken",
    "target_id": 22,
    "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": "deploy-token-name",
  "entity_path": "example-group/example-project",
  "target_details": "example-project",
  "created_at": "2022-07-26T05:46:25.850Z",
  "target_type": "Project",
  "target_id": 22,
  "event_type": "repository_git_operation"
}

来自极狐GitLab UI 下载按钮的事件负载示例

抓取： 

{
  "id": 1,
  "author_id": 99,
  "entity_id": 29,
  "entity_type": "Project",
  "details": {
    "custom_message": "Repository Download Started",
    "author_name": "example_username",
    "author_class": "User",
    "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
}

合并请求创建操作的审计事件流

引入于 15.2 版本。

使用 /logs 端点流式传输与合并请求创建操作相关的审计事件。

发送包含 X-Gitlab-Audit-Event-Type header 且值为 merge_request_create 的 API 请求。系统使用 JSON 有效负载进行响应，其中 event_type 字段设置为 merge_request_create。

Headers

格式如下： 

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

示例负载 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 24,
  "entity_type": "Project",
  "details": {
    "author_name": "example_user",
    "target_id": 132,
    "target_type": "MergeRequest",
    "target_details": "Update test.md",
    "custom_message": "Added merge request",
    "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": "Update test.md",
  "created_at": "2022-07-04T00:19:22.675Z",
  "target_type": "MergeRequest",
  "target_id": 132,
  "event_type": "merge_request_create"
}

项目派生操作的审计事件流

引入于 15.2 版本。

使用 /logs 端点流式传输与项目派生创建操作相关的审计事件。

发送包含 X-Gitlab-Audit-Event-Type 标头和值为 project_fork_operation 的 API 请求。系统使用 JSON 有效负载进行响应，其中 event_type 字段设置为 project_fork_operation。

Headers

格式如下： 

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

示例负载 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 24,
  "entity_type": "Project",
  "details": {
    "author_name": "example_username",
    "target_id": 24,
    "target_type": "Project",
    "target_details": "example-project",
    "custom_message": "Forked project to another-group/example-project-forked",
    "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-project",
  "created_at": "2022-06-30T03:43:35.384Z",
  "target_type": "Project",
  "target_id": 24,
  "event_type": "project_fork_operation"
}

项目群组关联操作的审计事件流

引入于 15.2 版本。

使用 /logs 端点流式传输与项目群组关联的创建、更新和删除相关的审计事件。

发送包含 X-Gitlab-Audit-Event-Type 标头的 API 请求，其值为：

  • project_group_link_create
  • project_group_link_update
  • project_group_link_destroy

系统使用 JSON 有效负载响应，并将 event_type 字段设置为：

  • project_group_link_create
  • project_group_link_update
  • project_group_link_destroy

示例 Headers

格式如下： 

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

创建项目群组关联的示例负载 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 24,
  "entity_type": "Project",
  "details": {
    "author_name": "example-user",
    "target_id": 31,
    "target_type": "Group",
    "target_details": "another-group",
    "custom_message": "Added project group link",
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "example-user",
  "entity_path": "example-group/example-project",
  "target_details": "another-group",
  "created_at": "2022-07-04T00:43:09.318Z",
  "target_type": "Group",
  "target_id": 31,
  "event_type": "project_group_link_create"
}

更新项目群组关联的示例负载 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 24,
  "entity_type": "Project",
  "details": {
    "author_name": "example-user",
    "target_id": 31,
    "target_type": "Group",
    "target_details": "another-group",
    "custom_message": "Changed project group link profile group_access from Developer to Guest",
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "example-user",
  "entity_path": "example-group/example-project",
  "target_details": "another-group",
  "created_at": "2022-07-04T00:43:28.328Z",
  "target_type": "Group",
  "target_id": 31,
  "event_type": "project_group_link_update"
}

删除项目群组关联的示例负载 

{
  "id": 1,
  "author_id": 1,
  "entity_id": 24,
  "entity_type": "Project",
  "details": {
    "author_name": "example-user",
    "target_id": 31,
    "target_type": "Group",
    "target_details": "another-group",
    "custom_message": "Removed project group link",
    "ip_address": "127.0.0.1",
    "entity_path": "example-group/example-project"
  },
  "ip_address": "127.0.0.1",
  "author_name": "example-user",
  "entity_path": "example-group/example-project",
  "target_details": "another-group",
  "created_at": "2022-07-04T00:42:56.279Z",
  "target_type": "Group",
  "target_id": 31,
  "event_type": "project_group_link_destroy"
}