Welcome to mirror list, hosted at ThFree Co, Russian Federation.

audit_events.md « administration « doc - gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
blob: e924da39145d2526801fb741e374f3f9e8df803d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
---
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/product/ux/technical-writing/#assignments
---

# Audit events **(PREMIUM)**

Use audit events to track important events, including who performed the related action and when.
You can use audit events to track, for example:

- Who changed the permission level of a particular user for a GitLab project, and when.
- Who added a new user or removed a user, and when.

Audit events are similar to the [log system](logs/index.md).

The GitLab API, database, and `audit_json.log` record many audit events. Some audit events are only available through
[streaming audit events](audit_event_streaming.md).

You can also generate an [audit report](audit_reports.md) of audit events.

NOTE:
You can't configure a retention policy for audit events, but epic
[7917](https://gitlab.com/groups/gitlab-org/-/epics/7917) proposes to change this.

## Time zones

> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/242014) in GitLab 15.7, GitLab UI shows dates and times in the user's local time zone instead of UTC.

The time zone used for audit events depends on where you view them:

- In GitLab UI, your local time zone (GitLab 15.7 and later) or UTC (GitLab 15.6 and earlier) is used.
- The [Audit Events API](../api/audit_events.md) returns dates and times in UTC by default, or the
  [configured time zone](timezone.md) on a self-managed GitLab instance.
- In `audit_json.log`, UTC is used.
- In CSV exports, UTC is used.

## View audit events

Depending on the events you want to view, at a minimum you must have:

- For group audit events of all users in the group, the Owner role for the group.
- For project audit events of all users in the project, the Maintainer role for the project.
- For group and project audit events based on your own actions, the Developer role for the group or project.
- [Auditor users](auditor_users.md) can see group and project events for all users.

You can view audit events scoped to a group or project.

To view a group's audit events:

1. Go to the group.
1. On the left sidebar, select **Security and Compliance > Audit Events**.

Group events do not include project audit events. Group events can also be accessed using the
[Group Audit Events API](../api/audit_events.md#group-audit-events). Group event queries are limited to a maximum of 30
days.

To view a project's audit events:

1. Go to the project.
1. On the left sidebar, select **Security & Compliance > Audit Events**.

Project events can also be accessed using the [Project Audit Events API](../api/audit_events.md#project-audit-events).
Project event queries are limited to a maximum of 30 days.

## View instance audit events **(PREMIUM SELF)**

You can view audit events from user actions across an entire GitLab instance.

To view instance audit events:

1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **Admin Area**.
1. On the left sidebar, select **Monitoring > Audit Events**.

### Export to CSV

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in GitLab 13.4.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in GitLab 13.7.

You can export the current view (including filters) of your instance audit events as a CSV file. To export the instance
audit events to CSV:

1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **Admin Area**.
1. On the left sidebar, select **Monitoring > Audit Events**.
1. Select the available search [filters](#filter-audit-events).
1. Select **Export as CSV**.

The exported file:

- Is sorted by `created_at` in ascending order.
- Is limited to a maximum of 100 000 events. The remaining records are truncated when this limit is reached.

Data is encoded with:

- Comma as the column delimiter.
- `"` to quote fields if necessary.
- New lines separate rows.

The first row contains the headers, which are listed in the following table along with a description of the values:

| Column               | Description                                        |
|:---------------------|:---------------------------------------------------|
| **ID**               | Audit event `id`.                                  |
| **Author ID**        | ID of the author.                                  |
| **Author Name**      | Full name of the author.                           |
| **Entity ID**        | ID of the scope.                                   |
| **Entity Type**      | Type of the scope (`Project`, `Group`, or `User`). |
| **Entity Path**      | Path of the scope.                                 |
| **Target ID**        | ID of the target.                                  |
| **Target Type**      | Type of the target.                                |
| **Target Details**   | Details of the target.                             |
| **Action**           | Description of the action.                         |
| **IP Address**       | IP address of the author who performed the action. |
| **Created At (UTC)** | Formatted as `YYYY-MM-DD HH:MM:SS`.                |

## View sign-in events **(FREE)**

Successful sign-in events are the only audit events available at all tiers. To see successful sign-in events:

1. Select your avatar.
1. Select **Edit profile > Authentication log**.

After upgrading to a paid tier, you can also see successful sign-in events on audit event pages.

## Filter audit events

From audit events pages, different filters are available depending on the page you're on.

| Audit event page | Available filter                                                                                                       |
|:-----------------|:-----------------------------------------------------------------------------------------------------------------------|
| Project          | User (member of the project) who performed the action.                                                                 |
| Group            | User (member of the group) who performed the action.                                                                   |
| Instance         | Group, project, or user.                                                                                               |
| All              | Date range buttons and pickers (maximum range of 31 days). Default is from the first day of the month to today's date. |

## User impersonation

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in GitLab 13.0.
> - Impersonation session events included in group audit events in GitLab 14.8.

When a user is [impersonated](../user/admin_area/index.md#user-impersonation), their actions are logged as audit events
with additional details:

- Audit events include information about the impersonating administrator. These audit events are visible in audit event
  pages depending on the audit event type (group, project, or user).
- Extra audit events are recorded for the start and end of the administrator's impersonation session. These audit events
  are visible as:
  - Instance audit events.
  - Group audit events for all groups the user belongs to. For performance reasons, group audit events are limited to
    the oldest 20 groups you belong to.

![Audit event with impersonated user](img/impersonated_audit_events_v15_7.png)

## Available audit events

You can view different events depending on the version of GitLab you have.

### Group events

The following actions on groups generate group audit events:

#### Group management

- Group name or path changed.
- Group repository size limit changed.
- Group created or deleted.
- Group changed visibility.
- User was added to group and with which [permissions](../user/permissions.md).
- Removed user from group.
- Project repository imported into group.
- [Project shared with group](../user/project/members/share_project_with_groups.md) and with which
  [permissions](../user/permissions.md).
- Removal of a previously shared group with a project.
- LFS enabled or disabled.
- Membership lock enabled or disabled.
- Request access enabled or disabled.
- Roles allowed to create project changed.
- Group deploy token was successfully created, revoked, or deleted.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353452) in GitLab 14.9.
- Failed attempt to create a group deploy token. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353452)
  in GitLab 14.9.
- [IP restrictions](../user/group/access_and_permissions.md#restrict-group-access-by-ip-address) changed.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358986) in GitLab 15.0.
- Group had a security policy project linked, changed, or unlinked.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) in GitLab 15.6.
- An environment is protected or unprotected.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) in GitLab 15.8.

#### Authentication and authorization

- User sign-in using [Group SAML](../user/group/saml_sso/index.md).
- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8071) in GitLab 14.5, changes to the following
  [group SAML](../user/group/saml_sso/index.md) configuration:
  - Enabled status.
  - Enforcing SSO-only authentication for web activity.
  - Enforcing SSO-only authentication for Git and Dependency Proxy activity.
  - Enforcing users to have dedicated group-managed accounts.
  - Prohibiting outer forks.
  - Identity provider SSO URL.
  - Certificate fingerprint.
  - Default membership role.
  - SSO-SAML group sync configuration.
- Permissions changes of a user assigned to a group.
- 2FA enforcement or grace period changed.

#### Compliance and security

- Compliance framework created, updated, or deleted.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340649) in GitLab 14.5.
- Event streaming destination created, updated, or deleted.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) in GitLab 14.6.
- Changes to push rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) in GitLab 15.0.
- Changes to streaming audit destination custom HTTP headers.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366350) in GitLab 15.3.
- Instance administrator started or stopped impersonation of a group member.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300961) in GitLab 14.8.

#### CI/CD

- Shared runners minutes limit changed.
- Group CI/CD variable added, removed, or protected status changed.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.3.

#### Code collaboration

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356152) in GitLab 15.1, changes to the following merge
  request approvals settings:
  - Prevent approval by author.
  - Prevent approvals by users who add commits.
  - Prevent editing approval rules in projects and merge requests.
  - Require user password to approve.
  - Remove all approvals when commits are added to the source branch.
- Changes to Code Suggestions.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405295) in GitLab 15.11.

### Project events

The following actions on projects generate project audit events:

#### Project management

- Added or removed deploy keys.
- Project created, deleted, renamed, moved (transferred), changed path.
- Project changed visibility level.
- Project export was downloaded.
- Project repository was downloaded.
- Project was archived.
- Project was unarchived.
- Project had a security policy project linked, changed, or unlinked.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) in GitLab 15.6.
- Project was scheduled for deletion due to inactivity.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0.
- Project deploy token was successfully created, revoked or deleted.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353451) in GitLab 14.9.
- Failed attempt to create a project deploy token.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353451) in GitLab 14.9.
- 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.

#### User management

- User was added to project and with which [permissions](../user/permissions.md).
- Permission changes of a user assigned to a project.
- User was removed from project.
- 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.

#### Access control

- Branch protection was added, removed, or updated.
- Failed attempt to create or revoke a project access token.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9.
- Allowing force push to protected branch changed.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3.
- An environment is protected or unprotected.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) in GitLab 15.8.
- User password required for approvals was updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2.
- Project access token was successfully created or revoked.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230007) in GitLab 13.9.

#### Code collaboration

- Default description template for merge requests is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) in GitLab 15.0.
- Merge commit message template is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) in GitLab 15.0.
- Squash commit message template is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) in GitLab 15.0.
- Delete source branch option by default enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Squash commits when merging is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- All discussions must be resolved enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Commit message suggestion is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Automatically resolve merge request diff discussions enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Show link to create or view a merge request when pushing from the command line enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- When merge method is updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Merge trains enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Code owner approval requirement on merge requests targeting protected branch changed.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3.
- 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.
- 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.
- Added or removed users and groups from project approval groups.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213603) in GitLab 13.2.
- Permission to approve merge requests by committers was updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9.
  - Message for event [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72623/diffs) in GitLab 14.6.
- Permission to approve merge requests by authors was updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9.
- Number of required approvals was updated.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9.

#### Release management

- Release was added to a project.
- Release was updated.
- Release was deleted. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94793/) in GitLab 15.3.
- Release milestone associations changed.

#### CI/CD

- Project CI/CD variable added, removed, or protected status changed.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4.
- When default branch changes for a project.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/52339) in GitLab 13.9.
- Pipelines must succeed enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Skipped pipelines are considered successful enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.
- Status check is added, edited, or deleted.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) in GitLab 15.0.
- Merged results pipelines enabled or disabled.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) in GitLab 14.9.

#### Compliance and security

- Created, updated, or deleted DAST profiles, DAST scanner profiles, and DAST site profiles.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1.
- Changed a project's compliance framework.
  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329362) in GitLab 14.1.

### GitLab agent for Kubernetes events

> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382133) in GitLab 15.10.

GitLab generates audit events when a cluster agent token is created or revoked.

### Instance events **(PREMIUM SELF)**

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5, audit events for failed second-factor authentication attempt.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6, audit events for when a user is approved using the Admin Area.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6, audit events for when a user's personal access token is successfully or unsuccessfully created or revoked.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298783) in GitLab 13.9, audit events for when a user requests access to an instance or is rejected using the Admin Area.

The following user actions on a GitLab instance generate instance audit events:

#### Authentication

- Sign-in events and the authentication type such as standard, LDAP, or OmniAuth.
- Failed sign-ins.
- Ask for password reset.
- Grant OAuth access.
- Failed second-factor authentication attempt.
- A user's personal access token was successfully or unsuccessfully created or revoked.
- A user's two-factor authentication was disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238177) in
  GitLab 15.1.

#### User management

- Added SSH key.
- Added or removed email.
- Changed password.
- Started or stopped user impersonation.
- Changed username.
- User was added or deleted.
- User requests access to an instance.
- User was approved, rejected, or blocked using the Admin Area.
- User was blocked using the API.
- Administrator added or removed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323905) in GitLab 14.1.
- Removed SSH key. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220127) in GitLab 14.1.
- Added or removed GPG key. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220127) in GitLab 14.1.
- Enabled Admin Mode. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) in GitLab 15.7.
- All [group events](#group-events) and [project events](#project-events).
- User was unblocked using the Admin Area or API. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115727) in GitLab 15.11.
- User was banned using the Admin Area or API. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116103) in GitLab 15.11.
- User was unbanned using the Admin Area or API. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116221) in GitLab 15.11.
- User was deactivated using the Admin Area or API. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117776) in GitLab 16.0.
- User was activated using the Admin Area or API. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121708) in GitLab 16.1.

Instance events can also be accessed using the [Instance Audit Events API](../api/audit_events.md#instance-audit-events).

### GitLab Runner events

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335509) in GitLab 14.8, audit events for when a runner is registered.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349540) in GitLab 14.9, audit events for when a runner is unregistered.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349542) in GitLab 14.9, audit events for when a runner is assigned to or unassigned from a project.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355637) in GitLab 15.0, audit events for when a runner registration token is reset.

GitLab generates audit events for the following GitLab Runner actions:

- Instance, group, or project runner is registered.
- Instance, group, or project runner is unregistered.
- Runner is assigned to or unassigned from a project.
- Instance, group, or project runner registration token is reset.
  [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102579) in GitLab 15.6.

## "Deleted User" events

Audit events created after users are deleted are created for "Deleted User". For example, if a deleted user's access to
a project is removed automatically due to expiration.

Issue [343933](https://gitlab.com/gitlab-org/gitlab/-/issues/343933) proposes to change this behavior.

## Unsupported events

Some events are not tracked in audit events. The following epics and issues propose support for more events:

- [Project settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/474).
- [Group settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/475).
- [Instance-level settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/476).
- [Deployment Approval activity](https://gitlab.com/gitlab-org/gitlab/-/issues/354782).
- [Approval rules processing by a non GitLab user](https://gitlab.com/gitlab-org/gitlab/-/issues/407384).

If you don't see the event you want in any of the epics, you can either:

- Use the **Audit Event Proposal** issue template to
  [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Audit%20Event%20Proposal) to
  request it.
- [Add it yourself](../development/audit_event_guide/index.md).