# Getting started with Audit Trails

Audit Trails collects [audit logs](concepts/format.md) of Yandex Cloud resources to monitor actions with resources and access events. You can upload logs to a Yandex Object Storage [bucket](../storage/concepts/bucket.md), Yandex Cloud Logging [log group](../logging/concepts/log-group.md), or Yandex Data Streams [data stream](../data-streams/concepts/glossary.md#stream-concepts).

Audit logs are collected and delivered to Audit Trails using [trails](concepts/trail.md). You need a separate trail for each storage type.

Follow this guide to create a trail to upload the audit logs of your organization’s resources. Select the destination object, depending on your goal:
* Object Storage [bucket](../storage/concepts/bucket.md) for long-term storage of audit logs and their future analysis.
* Cloud Logging [log group](../logging/concepts/log-group.md) to quickly view and search logs in real time. A good option for your first introduction to the service.

## Getting started {#before-you-begin}

This guide assumes that you already have Yandex Cloud resources, so first make sure that:

* You have a [cloud](../resource-manager/concepts/resources-hierarchy.md#cloud).
* Your cloud has a linked [billing account](../billing/concepts/billing-account.md) with the `ACTIVE` or `TRIAL_ACTIVE` status.

To create a trail, you will need the following roles:

* `iam.serviceAccounts.user` for the service account to collect audit logs. You can create this service account when creating the trail.
* `audit-trails.editor` for the folder to host the trail.
* `audit-trails.viewer` for the organization whose audit logs will be collected.
* If using a bucket:
   * `kms.editor` for the folder the bucket encryption key will be created in.
   * `storage.viewer` for the bucket or folder.
* If using a log group: `logging.viewer` for the log group or folder.

{% note info %}

If you cannot manage roles, contact your cloud or organization administrator.

{% endnote %}

## Creating a trail {#the-trail-creation}

{% list tabs group=audit-trails-destination %}

- Bucket {#bucket}

  1. In the [management console](https://console.yandex.cloud), select the folder to host the trail.
  1. Navigate to **Audit Trails**.
  1. Click **Create trail**.
  1. In the **Name** field, enter a name for the trail.
  1. Under **Destination**, configure the destination object:
      * **Destination**: `Object Storage`.
      * **Bucket**: Select the bucket to upload audit logs to. If you do not have a bucket yet, click **Create** and [create a new bucket](../storage/quickstart.md#the-first-bucket) with restricted access.
      * **Object prefix**: Optional parameter used in the [full name](concepts/format.md#log-file-name) of the audit log file.
      
      {% note info %}
      
      Use a [prefix](../storage/concepts/object.md#key) to store audit logs and third-party data in the same bucket. Do not use the same prefix for logs and other bucket objects because that may cause logs and third-party objects to overwrite each other.
      
      {% endnote %}
      * **Encryption key**: If the bucket you selected is [encrypted](../storage/concepts/encryption.md), specify the encryption key.
      
  1. Under **Service account**, select an existing [service account](../iam/concepts/users/service-accounts.md) or create a new one. The trail will use this account to upload audit log files to the bucket.
      If you are creating a new account, click **Create**, name the account, and and assign the following roles to it:
      * `storage.uploader` for the bucket.
      * `audit-trails.viewer` for the folder if planning to collect events from the folder.
      * `kms.keys.encrypter` for the encryption key if the bucket is encrypted.

  1. Under **Collecting management events**, set up the following:
      * **Collecting events**: `Enabled`.
      * **Resource**: Event collection level: `Organization`, `Cloud`, or `Folder`.
      * Depending on the event collection level you select:
          * Assign relevant roles to the service account. For example, if you select the **Folder** level, it will need the `audit-trails.viewer` role for this folder.
          * Specify an organization, cloud, or folder to collect audit logs from.

  1. Check **Collecting data events** and adjust the settings if required:
     
       {% note warning %}
       
       In the management console, collection of some [data events](concepts/control-plane-vs-data-plane.md#data-plane-events) is on [by default](concepts/trail.md#default). Their delivery is billed as per the [pricing policy](pricing.md). If you do not need data events, disable their collection.
       
       {% endnote %}
     
       * **Collecting events**: `Enabled`.
       * Select the [services](concepts/events-data-plane.md) to collect audit logs for.
       * For each service you select, specify the audit log collection [scope](concepts/trail.md#collecting-area) and event filter type:
     
           * `Receive all`: To receive all events within the service.
           * `Selected`: To receive only the selected events. Then proceed to select the [events](concepts/events-data-plane.md#dns).
           * `Exclude`: To receive all events except for the selected ones. Then proceed to select the events.
  1. Click **Create**.

- Log group {#log-group}

  1. In the [management console](https://console.yandex.cloud), select the folder to host the trail.
  1. [Navigate](../console/operations/select-service.md#select-service) to **Audit Trails**.
  1. Click **Create trail**.
  1. In the **Name** field, enter a name for the trail.
  1. Under **Destination**, configure the destination object:
      * **Destination**: `Cloud Logging`.
      * **Log group**: Select a log group to upload audit logs to. If you do not have a log group yet, click **Create** and [create a new log group](../logging/quickstart.md).

  1. Under **Service account**, select an existing [service account](../iam/concepts/users/service-accounts.md) or create a new one. The trail will use this account to upload audit log files to the log group.
      If you are creating a new account, click **Create**, name the account, and and assign the following roles to it:
      * `logging.writer` for the log group.
      * `audit-trails.viewer` for the folder if planning to collect events from the folder.

  1. Under **Collecting management events**, configure the collection of management event audit logs:
      * **Collecting events**: Select `Enabled`.
      * **Resource**: Select the event collection level: `Organization`, `Cloud`, or `Folder`.
      * Depending on the event collection level you select:
          * Assign relevant roles to the service account. For example, if you select the **Folder** level, it will need the `audit-trails.viewer` role for this folder.
          * Specify an organization, cloud, or folder to collect audit logs from.

  1. Check **Collecting data events** and adjust the settings if required:
     
       {% note warning %}
       
       In the management console, collection of some [data events](concepts/control-plane-vs-data-plane.md#data-plane-events) is on [by default](concepts/trail.md#default). Their delivery is billed as per the [pricing policy](pricing.md). If you do not need data events, disable their collection.
       
       {% endnote %}
     
       * **Collecting events**: `Enabled`.
       * Select the [services](concepts/events-data-plane.md) to collect audit logs for.
       * For each service you select, specify the audit log collection [scope](concepts/trail.md#collecting-area) and event filter type:
     
           * `Receive all`: To receive all events within the service.
           * `Selected`: To receive only the selected events. Then proceed to select the [events](concepts/events-data-plane.md#dns).
           * `Exclude`: To receive all events except for the selected ones. Then proceed to select the events.
  1. Click **Create**.

{% endlist %}

You can also create a trail using the [CLI](operations/create-trail.md#cli), [Terraform](operations/create-trail.md#tf), or [API](operations/create-trail.md#api).

{% note info %}

Changing the destination object of an existing trail may result in the loss of some events. To prevent data loss, create a dedicated trail for each destination object.

{% endnote %}

## Viewing audit logs {#watch-logs}

{% list tabs group=audit-trails-destination %}

- Bucket {#bucket}

  Audit Trails generates audit log files approximately once every 5 minutes. Audit Trails creates log files in `JSON` format.
  
  Access to the contents of the audit log file using one of the following methods:
  * [Download the object](../storage/operations/objects/download.md).
  * [Get a public link to the object](../storage/operations/objects/link-for-download.md).
  * Mount the bucket using [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace): [s3fs](../storage/tools/s3fs.md) or [goofys](../storage/tools/goofys.md).

- Log group {#log-group}

  In the Cloud Logging UI, you can view audit logs in real time.
  
  1. In the [management console](https://console.yandex.cloud), select the folder with the log group.
  1. Select **Cloud Logging**.
  1. Click the row with the log group.
  1. Navigate to the **Logs** tab.
  1. Configure event search filters.

{% endlist %}

## Exporting audit logs to SIEM {#export-to-siem}

You can [export](concepts/export-siem.md) audit log files to your SIEM solution.

## What's next {#whats-next}

* Learn more about the [service](concepts/index.md).
* Learn more about the [types of audit logs](concepts/control-plane-vs-data-plane.md).
* Read about [audit log requirements in the security standard](../security/standard/audit-logs.md).