gitlab-org--gitlab-foss/doc/administration/audit_event_streaming.md

stage	group	info
Manage	Compliance	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

Audit event streaming (ULTIMATE)

• Introduced in GitLab 14.5 with a flag named ff_external_audit_events_namespace. Disabled by default.
• Enabled on GitLab.com and by default on self-managed in GitLab 14.7.
• Feature flag ff_external_audit_events_namespace removed in GitLab 14.8.

Event streaming allows owners of top-level groups to set an HTTP endpoint to receive all audit events about the group, and its subgroups and projects as structured JSON.

Top-level group owners can manage their audit logs in third-party systems such as Splunk, using the Splunk HTTP Event Collector. Any service that can receive structured JSON data can be used as the endpoint.

NOTE: GitLab can stream a single event more than once to the same destination. Use the id key in the payload to deduplicate incoming data.

Add a new event streaming destination

WARNING: Event streaming destinations will receive all audit event data, which could include sensitive information. Make sure you trust the destination endpoint.

To enable event streaming, a group owner must add a new event streaming destination using the externalAuditEventDestinationCreate mutation in the GraphQL API.

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

Event streaming is enabled if:

• The returned errors object is empty.
• The API responds with 200 OK.

List currently enabled streaming destinations

Group owners can view a list of event streaming destinations at any time using the externalAuditEventDesinations query type.

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

If the resulting list is empty, then audit event streaming is not enabled for that group.

Verify event authenticity

Introduced 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.

Each streamed event contains a random alphanumeric identifier for the X-Gitlab-Event-Streaming-Token HTTP header that can be verified against the destination's value when listing streaming destinations.