diff options
Diffstat (limited to 'doc/administration/audit_event_streaming.md')
| -rw-r--r-- | doc/administration/audit_event_streaming.md | 42 |
1 files changed, 31 insertions, 11 deletions
diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md index 3bb0ce41861..9ec7b81bfd0 100644 --- a/doc/administration/audit_event_streaming.md +++ b/doc/administration/audit_event_streaming.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -16,7 +16,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Custom HTTP headers API [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366524) in GitLab 15.3. [Feature flag `streaming_audit_event_headers`](https://gitlab.com/gitlab-org/gitlab/-/issues/362941) removed. > - Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default. > - Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed. -> - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.4. +> - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3. +> - User-specified verification token API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360813) in GitLab 15.4. Users can set a streaming destination for a top-level group to receive all audit events about the group, its subgroups, and projects as structured JSON. @@ -38,7 +39,7 @@ Streaming destinations receive **all** audit event data, which could include sen Users with the Owner role for a group can add streaming destinations for it: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select **Streams** tab. 1. Select **Add streaming destination** to show the section for adding destinations. @@ -71,6 +72,25 @@ mutation { } ``` +Group owners can also optionally specify their own verification token (instead of the default GitLab-generated one) using the GraphQL `auditEventsStreamingHeadersCreate` +mutation. Verification token length must be within 16 to 24 characters and trailing whitespace are not trimmed. GitLab recommends setting a cryptographically random and unique value. For example: + +```graphql +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 + } + } + } +} +``` + Event streaming is enabled if: - The returned `errors` object is empty. @@ -97,7 +117,7 @@ Users with the Owner role for a group can list streaming destinations. To list the streaming destinations: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select **Streams** tab. 1. To the right of the item, select **Edit** (**{pencil}**) to see all the custom HTTP headers. @@ -141,7 +161,7 @@ Users with the Owner role for a group can update streaming destinations. To update a streaming destinations custom HTTP headers: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select **Streams** tab. 1. To the right of the item, select **Edit** (**{pencil}**). @@ -195,14 +215,14 @@ When the last destination is successfully deleted, streaming is disabled for the To delete a streaming destination: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select the **Streams** tab. 1. To the right of the item, select **Delete** (**{remove}**). To delete only the custom HTTP headers for a streaming destination: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select the **Streams** tab. 1. To the right of the item, **Edit** (**{pencil}**). @@ -248,9 +268,9 @@ The header is deleted if the returned `errors` object is empty. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345424) in GitLab 14.8. Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This -token is generated when the event destination is created and cannot be changed. +token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed. -Each streamed event contains a random alphanumeric identifier for the `X-Gitlab-Event-Streaming-Token` HTTP header that can be verified against +Each streamed event contains the verification token in the `X-Gitlab-Event-Streaming-Token` HTTP header that can be verified against the destination's value when [listing streaming destinations](#list-streaming-destinations). ### Use the GitLab UI @@ -259,7 +279,7 @@ the destination's value when [listing streaming destinations](#list-streaming-de Users with the Owner role for a group can list streaming destinations and see the verification tokens: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Audit events**. 1. On the main area, select the **Streams**. 1. View the verification token on the right side of each item. @@ -297,7 +317,7 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](feature_flags.md) named `audit_event_streaming_git_operations`. -Streaming audit events can be sent when signed-in users push or pull a project's remote Git repositories: +Streaming audit events can be sent when signed-in users push, pull, or clone a project's remote Git repositories: - [Using SSH](../user/ssh.md). - Using HTTP or HTTPS. |