From 585826cb22ecea5998a2c2a4675735c94bdeedac Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Tue, 14 Nov 2023 08:41:52 +0000 Subject: Add latest changes from gitlab-org/gitlab@16-6-stable-ee --- doc/administration/audit_events.md | 181 ++++++++++++++++--------------------- 1 file changed, 78 insertions(+), 103 deletions(-) (limited to 'doc/administration/audit_events.md') diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 736f381e9d7..ba1a4ca05c4 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -6,171 +6,146 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Audit events **(PREMIUM ALL)** -Use audit events to track important events, including who performed the related action and when. -You can use audit events to track, for example: +A security audit is a in-depth analysis and review of your infrastructure, which is used to display +areas of concern and potentially hazardous practices. To assist with the audit process, GitLab provides +audit events which allow you to track a variety of different actions within GitLab. + +For example, you can use audit events to track: - 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). +These events can be used to in an audit to assess risk, strengthen security measures, respond to incidents, and adhere to compliance. For a complete list the audit events GitLab provides, see [Audit event types](../administration/audit_event_streaming/audit_event_types.md). -You can also generate an [audit report](audit_reports.md) of audit events. +## Prerequisites -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. +To view specific types of audit events, you need a minimum role. -## 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. +- To view the group audit events of all users in a group, you must have the [Owner role](../user/permissions.md#roles) for the group. +- To view the project audit events of all users in a project, you must have at least the [Maintainer role](../user/permissions.md#roles) for the project. +- To view the group and project audit events based on your own actions in a group or project, you must have at least the [Developer role](../user/permissions.md#roles) + for the group or project. -The time zone used for audit events depends on where you view them: +Users with the [Auditor access level](auditor_users.md) can see group and project events for all users. -- 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. +## Viewing audit events -## View audit events +Audit events can be viewed at the group, project, instance, and sign-in level. Each level has different audit events which it logs. -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. +### Group audit events To view a group's audit events: -1. Go to the group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Audit events**. +1. Filter the audit events by the member of the project (user) who performed the action and date range. -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. +Group audit events can also be accessed using the [Group Audit Events API](../api/audit_events.md#group-audit-events). Group audit event queries are limited to a maximum of 30 days. -To view a project's audit events: +### Project audit events -1. Go to the project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Secure > Audit events**. +1. Filter the audit events by the member of the project (user) who performed the action and date range. -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. +Project audit events can also be accessed using the [Project Audit Events API](../api/audit_events.md#project-audit-events). Project audit event queries are limited to a maximum of 30 days. -## View instance audit events **(PREMIUM SELF)** +### Instance audit events **(PREMIUM SAAS)** You can view audit events from user actions across an entire GitLab instance. - To view instance audit events: 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Audit Events**. +1. Filter by the following: + - Member of the project (user) who performed the action + - Group + - Project + - Date Range + +### Sign-in audit events **(FREE ALL)** + +Successful sign-in events are the only audit events available at all tiers. To see successful sign-in events: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile > Authentication log**. -### Export to CSV +After upgrading to a paid tier, you can also see successful sign-in events on audit event pages. + +## Exporting audit events > - [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. > - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2. -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: +You can export the current view (including filters) of your instance audit events as a +CSV(comma-separated values) file. To export the instance audit events to CSV: 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Audit Events**. -1. Select the available search [filters](#filter-audit-events). +1. Select the available search filters. 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. +A download confirmation dialog then appears for you to download the CSV file. The exported CSV is limited +to a maximum of 100000 events. The remaining records are truncated when this limit is reached. -The first row contains the headers, which are listed in the following table along with a description of the values: +### Audit event CSV encoding -| 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`, `User`, or `Gitlab::Audit::InstanceScope`). | -| **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`. | +The exported CSV file is encoded as follows: -## View sign-in events **(FREE ALL)** +- `,` is used as the column delimiter +- `"` is used to quote fields if necessary. +- `\n` is used to separate rows. -Successful sign-in events are the only audit events available at all tiers. To see successful sign-in events: +The first row contains the headers, which are listed in the following table along +with a description of the values: -1. On the left sidebar, 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. +| 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`, `User`, or `Gitlab::Audit::InstanceScope`). | +| **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`. | -## 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. | +All items are sorted by `created_at` in ascending order. ## 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](../administration/admin_area.md#user-impersonation), their actions are logged as audit events -with additional details: +When a user is [impersonated](../administration/admin_area.md#user-impersonation), their actions are logged as audit events with the following 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 events include information about the impersonating administrator. +- Extra audit events are recorded for the start and end of the administrator's impersonation session. ![Audit event with impersonated user](img/impersonated_audit_events_v15_7.png) -## Available audit events +## Time zones -For a list of available audit events, see [Audit event types](../administration/audit_event_streaming/audit_event_types.md). +> [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. -## Unsupported events +The time zone used for audit events depends on where you view them: -Some events are not tracked in audit events. The following epics and issues propose support for more events: +- 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 CSV exports, UTC is used. -- [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). +## Contribute to audit events 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. + [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). -- cgit v1.2.3