1--- 2stage: Manage 3group: Compliance 4info: 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 5--- 6 7# Audit Events **(PREMIUM)** 8 9GitLab offers a way to view the changes made within the GitLab server for owners and administrators 10on a [paid plan](https://about.gitlab.com/pricing/). 11 12GitLab system administrators can also view all audit events by accessing the [`audit_json.log` file](logs.md#audit_jsonlog). 13 14You can: 15 16- Generate an [audit report](audit_reports.md) of audit events. 17- [Stream audit events](audit_event_streaming.md) to an external endpoint. 18 19## Overview 20 21**Audit Events** is a tool for GitLab owners and administrators 22to track important events such as who performed certain actions and the 23time they happened. For example, these actions could be a change to a user 24permission level, who added a new user, or who removed a user. 25 26## Use cases 27 28- Check who changed the permission level of a particular 29 user for a GitLab project. 30- Track which users have access to a certain group of projects 31 in GitLab, and who gave them that permission level. 32 33## Retention policy 34 35There is no retention policy in place for audit events. 36See the [Specify a retention period for audit events](https://gitlab.com/gitlab-org/gitlab/-/issues/8137) for more information. 37 38## List of events 39 40There are two kinds of events logged: 41 42- Events scoped to the group or project, used by group and project managers 43 to look up who made a change. 44- Instance events scoped to the whole GitLab instance, used by your Compliance team to 45 perform formal audits. 46 47### Impersonation data 48 49> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in GitLab 13.0. 50 51When a user is being [impersonated](../user/admin_area/index.md#user-impersonation), their actions are logged as audit events as usual, with two additional details: 52 531. Usual audit events include information about the impersonating administrator. These are visible in their respective Audit Event pages depending on their type (Group/Project/User). 541. Extra audit events are recorded for the start and stop of the administrator's impersonation session. These are visible in the instance Audit Events. 55 56 57 58### Group events 59 60A user with: 61 62- Owner role (or above) can retrieve group audit events of all users. 63- Developer or Maintainer role is limited to group audit events based on their individual actions. 64 65Group events do not include project audit events. 66 67To view a group's audit events: 68 691. Go to the group. 701. On the left sidebar, select **Security & Compliance > Audit Events**. 71 72From there, you can see the following actions: 73 74- Group name or path changed. 75- Group repository size limit changed. 76- Group created or deleted. 77- Group changed visibility. 78- User was added to group and with which [permissions](../user/permissions.md). 79- User sign-in via [Group SAML](../user/group/saml_sso/index.md). 80- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8071) in GitLab 14.5, changes to the following 81 [group SAML](../user/group/saml_sso/index.md) configuration: 82 - Enabled status. 83 - Enforcing SSO-only authentication for web activity. 84 - Enforcing SSO-only authentication for Git and Dependency Proxy activity. 85 - Enforcing users to have dedicated group-managed accounts. 86 - Prohibiting outer forks. 87 - Identity provider SSO URL. 88 - Certificate fingerprint. 89 - Default membership role. 90 - SSO-SAML group sync configuration. 91- Permissions changes of a user assigned to a group. 92- Removed user from group. 93- Project repository imported into group. 94- [Project shared with group](../user/project/members/share_project_with_groups.md) 95 and with which [permissions](../user/permissions.md). 96- Removal of a previously shared group with a project. 97- LFS enabled or disabled. 98- Shared runners minutes limit changed. 99- Membership lock enabled or disabled. 100- Request access enabled or disabled. 101- 2FA enforcement or grace period changed. 102- Roles allowed to create project changed. 103- Group CI/CD variable added, removed, or protected status changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.3. 104- Compliance framework created, updated, or deleted. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340649) in GitLab 14.5. 105- Event streaming destination created, updated, or deleted. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) in GitLab 14.6. 106 107Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events) 108 109### Project events 110 111A user with a Maintainer role (or above) can retrieve project audit events of all users. 112A user with a Developer role is limited to project audit events based on their individual actions. 113 114To view a project's audit events: 115 1161. Go to the project. 1171. On the left sidebar, select **Security & Compliance > Audit Events**. 118 119From there, you can see the following actions: 120 121- Added or removed deploy keys 122- Project created, deleted, renamed, moved (transferred), changed path 123- Project changed visibility level 124- User was added to project and with which [permissions](../user/permissions.md) 125- Permission changes of a user assigned to a project 126- User was removed from project 127- Project export was downloaded 128- Project repository was downloaded 129- Project was archived 130- Project was unarchived 131- Added, removed, or updated protected branches 132- Release was added to a project 133- Release was updated 134- Release milestone associations changed 135- Permission to approve merge requests by committers was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) 136- Permission to approve merge requests by committers was updated. 137 - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9. 138 - Message for event [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72623/diffs) in GitLab 14.6. 139 140- Permission to approve merge requests by authors was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) 141- Number of required approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) 142- Added or removed users and groups from project approval groups ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213603) in GitLab 13.2) 143- Project CI/CD variable added, removed, or protected status changed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4) 144- Project access token was successfully created or revoked ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9) 145- Failed attempt to create or revoke a project access token ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9) 146- When default branch changes for a project ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/52339) in GitLab 13.9) 147- Created, updated, or deleted DAST profiles, DAST scanner profiles, and DAST site profiles 148 ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1) 149- Changed a project's compliance framework ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329362) in GitLab 14.1) 150- User password required for approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) 151- Permission to modify merge requests approval rules in merge requests was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) 152- New approvals requirement when new commits are added to an MR was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) 153- When [strategies for feature flags](../operations/feature_flags.md#feature-flag-strategies) are changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68408) in GitLab 14.3) 154- Allowing force push to protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) 155- Code owner approval requirement on merge requests targeting protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) 156- Users and groups allowed to merge and push to protected branch added or removed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) 157 158Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events). 159 160Project event queries are limited to a maximum of 30 days. 161 162### Instance events **(PREMIUM SELF)** 163 164Server-wide audit events introduce the ability to observe user actions across 165the entire instance of your GitLab server, making it easy to understand who 166changed what and when for audit purposes. 167 168Instance events do not include group or project audit events. 169 170To view the server-wide audit events: 171 1721. On the top bar, select **Menu > Admin**. 1731. On the left sidebar, select **Monitoring > Audit Events**. 174 175The following user actions are recorded: 176 177- Sign-in events and the authentication type (such as standard, LDAP, or OmniAuth) 178- Failed sign-ins 179- Added SSH key 180- Added or removed email 181- Changed password 182- Ask for password reset 183- Grant OAuth access 184- Started or stopped user impersonation 185- Changed username ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7797) in GitLab 12.8) 186- User was deleted ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) 187- User was added ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) 188- User requests access to an instance ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9) 189- User was approved via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6) 190- User was rejected via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9) 191- User was blocked via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) 192- User was blocked via API ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25872) in GitLab 12.9) 193- Failed second-factor authentication attempt ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5) 194- A user's personal access token was successfully created or revoked ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6) 195- A failed attempt to create or revoke a user's personal access token ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6) 196- Administrator added or removed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323905) in GitLab 14.1) 197- Removed SSH key ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220127) in GitLab 14.1) 198- Added or removed GPG key ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220127) in GitLab 14.1) 199 200Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events). 201 202### Sign-in events **(FREE)** 203 204Successful sign-in events are the only Audit Events available at all tiers. To see 205successful sign-in events: 206 2071. Select your avatar. 2081. Select **Edit profile > Authentication log**. 209 210After upgrading from GitLab Free to a paid tier, successful sign-in events are the only Audit 211Events visible in Audit Events views until more events are logged. 212 213### "Deleted User" events 214 215Audit events can be created for a user after the user is deleted. The user name associated with the event is set to 216"Deleted User" because the actual user name is unknowable. For example, if a deleted user's access to a project is 217removed automatically due to expiration, the audit event is created for "Deleted User". We are [investigating](https://gitlab.com/gitlab-org/gitlab/-/issues/343933) 218whether this is avoidable. 219 220### Missing events 221 222Some events are not tracked in audit events. See the following 223epics for more detail on which events are not being tracked, and our progress 224on adding these events into GitLab: 225 226- [Project settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/474) 227- [Group settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/475) 228- [Instance-level settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/476) 229 230Don't see the event you want in any of the epics linked above? You can either: 231 232- Use the **Audit Event Proposal** issue template to 233 [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Audit%20Event%20Proposal) to 234 request it. 235- [Add it yourself](../development/audit_event_guide/). 236 237### Disabled events 238 239#### Repository push 240 241> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/337993) in GitLab 14.3. 242 243The current architecture of audit events is not prepared to receive a very high amount of records. 244It may make the user interface for your project or audit events very busy, and the disk space consumed by the 245`audit_events` PostgreSQL table may increase considerably. It's disabled by default 246to prevent performance degradations on GitLab instances with very high Git write traffic. 247 248If you still wish to enable **Repository push** events in your instance, follow 249the steps below. 250 251**In Omnibus installations:** 252 2531. Enter the Rails console: 254 255 ```shell 256 sudo gitlab-rails console 257 ``` 258 2591. Flip the switch and enable the feature flag: 260 261 ```ruby 262 Feature.enable(:repository_push_audit_event) 263 ``` 264 265## Search 266 267The search filters you can see depends on which audit level you are at. 268 269| Filter | Available options | 270| ------ | ----------------- | 271| Scope (Project level) | A specific user who performed the action. | 272| Scope (Group level) | A specific user (in a group) who performed the action. | 273| Scope (Instance level) | A specific group, project, or user that the action was scoped to. | 274| Date range | Either via the date range buttons or pickers (maximum range of 31 days). Default is from the first day of the month to today's date. | 275 276 277 278## Export to CSV **(PREMIUM SELF)** 279 280> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in GitLab 13.4. 281> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in GitLab 13.7. 282 283Export to CSV allows customers to export the current filter view of your audit events as a 284CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to 285audit events. 286 287To export the audit events to CSV: 288 2891. On the top bar, select **Menu > Admin**. 2901. On the left sidebar, select **Monitoring > Audit Events**. 2911. Select the available search [filters](#search). 2921. Select **Export as CSV**. 293 294### Sort 295 296Exported events are always sorted by `created_at` in ascending order. 297 298### Format 299 300Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. 301The first row contains the headers, which are listed in the following table along with a description of the values: 302 303| Column | Description | 304|---------|-------------| 305| ID | Audit event `id` | 306| Author ID | ID of the author | 307| Author Name | Full name of the author | 308| Entity ID | ID of the scope | 309| Entity Type | Type of the scope (`Project`/`Group`/`User`) | 310| Entity Path | Path of the scope | 311| Target ID | ID of the target | 312| Target Type | Type of the target | 313| Target Details | Details of the target | 314| Action | Description of the action | 315| IP Address | IP address of the author who performed the action | 316| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | 317 318### Limitation 319 320The audit events CSV file is limited to a maximum of `100,000` events. 321The remaining records are truncated when this limit is reached. 322
