Add latest changes from gitlab-org/gitlab@16-6-stable-eev16.6.0-rc42

1 files changed, 78 insertions, 103 deletions

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