Audit event schema and examples

Audit event schema

Audit events have a predictable schema in the body of the response.

Audit event JSON schema

{
  "properties": {
    "id": {
      "type": "string"
    },
    "author_id": {
      "type": "integer"
    },
    "author_name": {
      "type": "string"
    },
    "details": {},
    "ip_address": {
      "type": "string"
    },
    "entity_id": {
      "type": "integer"
    },
    "entity_path": {
      "type": "string"
    },
    "entity_type": {
      "type": "string"
    },
    "event_type": {
      "type": "string"
    },
    "target_id": {
      "type": "integer"
    },
    "target_type": {
      "type": "string"
    },
    "target_details": {
      "type": "string"
    },
  },
  "type": "object"
}

GitLab Duo-related events

When an audit event is related to the GitLab Duo Agent Platform, the details object includes a duo_related field set to true.

The following events can include this field:

Use this field to identify GitLab Duo Agent Platform activity in your Security Information and Event Management (SIEM) tool or other external tools, instead of service account naming patterns.

Events created with a composite identity

When a service account performs an action on behalf of a human user with a composite identity, the audit event is attributed to the service account:

• author_id contains the user ID of the service account.
• author_name contains <service account name> on behalf of @<human username>, truncated to 255 characters. This value appears in the Author column on audit event pages and in CSV exports.

The details object records the human user who authorized the action:

These fields are included in streamed audit events and in the details object returned by the audit events API.

For these events, the author_class field in the details object contains Gitlab::Audit::CompositeIdentityAuthor. Use this value to identify composite identity events in your SIEM or other external tools.

AI agent session events, such as ai_agent_session_started and ai_tool_invoked, also record the human_author_* fields but do not use this author_class value. To match both kinds of events, filter on the presence of human_author_id instead.

When a human user performs the action and a service account only participates in the action, for example when the human user assigns a service account as a merge request reviewer, the audit event is attributed to the human user and the human_author_* fields are not added.

Headers

Headers are formatted as follows:

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

Example: audit event streaming on Git operations

Streaming audit events can be sent when authenticated users push, pull, or clone a project’s remote Git repositories:

• Using SSH.
• Using HTTP or HTTPS.
• Using Download ( ) in GitLab UI.

Audit events are not captured for users that are not signed in. For example, when downloading a public project.

Example: audit event payloads for Git over SSH events with deploy key

Fetch:

{
  "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",
      "written_bytes": 1048576,
      "received_bytes": 2048,
      "gl_key_type": "deploy_key",
      "gl_key_id": 24
    },
    "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"
}

The custom_message object includes data transfer size fields for Git operations:

• written_bytes: Number of bytes sent to the client during the Git operation (for example, during a clone, fetch, or pull).
• received_bytes: Number of bytes received from the client during the Git operation (for example, during a push).

These fields are omitted when no bytes are transferred, such as when a request fails before any data is exchanged.

The custom_message object includes key information for Git operations authenticated with an SSH key or deploy key:

• gl_key_type: Type of the key used for authentication. Either key for user SSH keys, or deploy_key for deploy keys.
• gl_key_id: ID of the key used for authentication.

These fields are omitted when the operation is not authenticated with a key, for example HTTP(S) with a username and password, or a deploy token.