Trail

A trail is an Audit Trails resource that collects audit logs of Yandex Cloud resources and writes them to an Object Storage bucket, Cloud Logging log group, or Data Streams data flow.

Collecting and filtering eventsCollecting and filtering events

When creating or updating a trail, you can select which events it should write to the destination object.

Collection scopeCollection scope

The collection scope determines the source of events for a trail:

• Organization: All clouds or selected clouds within the current organization.
• Cloud: All or selected folders of the current cloud.
• Folder: Current folder.

New resources created in the selected scope are automatically included in event collection. The same collection conditions apply to their events.

Collecting management eventsCollecting management events

Management events capture operations related to setting up cloud resources, e.g., creating a VM or deleting a database cluster.

For this level, you only need to define the collection scope. Within this scope, the system automatically collects events from all the supported services, without filtering for specific services or event names. You can enable or disable collection as a whole.

Collecting data eventsCollecting data events

For data events, you can select services, and for each service, define the collection scope and conditions. You can disable collection globally or for individual services.

There are three event collection types:

• Get all: Collect all current and future events.
• Selected (included_events): Only collect events with the specified names. New names are not added to the list automatically.
• Exclude (excluded_events): Collect all events except those specified. New events will be collected automatically.

In a single filter, you can only specify event names in one of the sections: included_events or excluded_events. If both of the sections are empty, all data events will be collected based on the other filtering conditions.

You can find the event names in the data event reference. In the CLI, Terraform, or API, use a full name from the event_type field of the audit log, e.g., yandex.cloud.audit.iam.CreateIamToken.

Field value conditionsField value conditions

When using the CLI, Terraform , and API, you can add field value conditions to the data event filter, e.g., to exclude events of a specific user. These conditions apply together with the selected collection scope and event names.

You can set filtering rules in one or both sections:

• include_rules: Which events to log.
• exclude_rules: Which events to discard.

A single rule is a conditions section with a set of conditions. A rule is triggered if all of its conditions are met (logical AND). If include_rules or exclude_rules feature multiple rules, it is enough to trigger at least one of them (logical OR).

Each condition contains:

• field: Path from the event root ($) to a scalar value, e.g., $.details.bucket_id, $.details.user.groups[0], or $.details.items[2].metadata['name']. Array indexes start from zero.
• operator: Comparison operator:
  • IN: Field value matches one of those in the values list.
  • IP_IN: IP address from the field is part of one of the subnets specified in values in CIDR format.
• values: List containing from one to 64 values. Values should be specified as strings, including for numeric and boolean fields.

A rule can contain from one to 64 conditions; each list can contain up to 64 rules.

The fields depend on event type as per the reference, e.g., for ObjectCreate. The request_parameters and response fields and their content cannot be filtered.

Key names and case in the path must match the actual audit log JSON. For example, use $.event_type and $.request_metadata.remote_address, even though the reference names these fields eventType and requestMetadata.remoteAddress.

Filter structure example:

include_rules:  # Including events; to exclude, use exclude_rules
  - conditions:  # Rule 1: condition 1 AND condition 2
      - field: "<path_to_field_1>"
        operator: IN
        values: ["<value_1>", "<value_2>"]
      - field: "<path_to_field_2>"
        operator: IP_IN
        values: ["<subnet_in_cidr>"]
  - conditions:  # OR rule 2
      - field: "<path_to_field_3>"
        operator: IN
        values: ["<value_3>"]

For filter examples, see Filtering by field value.

Pre-installed eventsPre-installed events

When creating a trail in the management console, some data events are collected by default. This is done for security in line with the cloud infrastructure protection standard. If a service is not used, you can disable the events. Delivered events are billed as per the pricing policy.

Services for which the sending of events is on by default:

Destination objectDestination object

Each trail uploads audit logs only to a single destination object: a bucket, a log group, or a data stream.

Each destination object has its advantages:

• Object Storage: Provides long-term storage of large amounts of data for further processing.
• Cloud Logging: Helps respond to events and analyze logs in real time.
• Data Streams: Enables streaming data to other services and systems.

When uploading audit logs to a bucket, Audit Trails generates files about once every 5 minutes. Filtered events from the selected collection scope will be saved into one or multiple files. If there are no matching events during this period, files will not be generated.

Audit Trails uploads audit logs to log groups and data stream in near real time.

The type of destination object determines the structure and content of the message used by Audit Trails to transmit audit logs:

• If the destination object is a bucket, the message is a file containing a JSON object array of the audit log.
• If the destination object is a log group, the message includes a single JSON object of the audit log.
• If the destination object is a data stream, the messages containing JSON objects of the audit log are sent to the stream.

Each trail runs independently of one another. Using multiple trails, you can differentiate access to various log groups for users and services according to your information security policy.

Trail settingsTrail settings

In the management console, the following trail settings are available:

• Name: Required parameter.
• Description: Optional parameter.
• Destination section:
  • Destination: Object Storage, Cloud Logging, or Data Streams.
  • For the Object Storage value:
    • Bucket: Bucket.
    • Object prefix: Optional parameter used in the full name of the audit log file.
    • Encryption key: Yandex Key Management Service symmetric encryption key for the bucket.
  • For the Cloud Logging value:
    • Log group: Log group.
  • For the Data Streams value:

    • Data stream: Data stream.

    • Codec: Event compression method when writing to Data Streams.

      If the event flow write speed in Data Streams is over 1 MB/s, enable compression. This will cut the volume of transmitted data, reduce the risk of throttling for individual YDS segments, and improve your flow bandwidth performance.

      The compression setting is available when creating or modifying a trail via the CLI, API, or Terraform UI. Available compression methods: GZIP (GNU Zip) or ZSTD (Zstandard). There is no compression default (RAW).

      To read data via the native YDS protocol, additionally enable compression on the YDS reader. The HTTP Kinesis and Apache Kafka® protocols are not supported yet.

• Service account section: Service account to use for uploading audit logs to a bucket, a log group, or a data stream. If the account needs more roles, a warning with a list of roles will show up.
• Control plane log collection section:
  • Status: Toggles the collection of management event audit logs.
  • Resource: Organization, Cloud, or Folder.
  • For the Organization value:
    • Organization: Name of the current organization. The value is populated automatically.
  • For the Cloud value:
    • Cloud: Name of the cloud hosting the current trail. The value is populated automatically.
    • Folder: Folders for whose resources the trail will collect management event audit logs. If you do not specify any folder, the trail will collect audit logs from all resources in the cloud.
  • For the Folder parameter:
    • Folder: Name of the folder hosting the trail. The value is populated automatically.
• Data plane log collection section:
  • Status: Toggles the collection of data event audit logs.
  • List of services, each configured individually for:
    • Data event audit log collection scope.
    • Event filter type:
      • Receive all: To receive all events within the service.
      • Selected: To only receive the selected events.
      • Exclude: To receive all events except for the selected ones.
    • List of events is Selected or Exclude filter type is selected.

Use casesUse cases

• Searching for events in audit logs
• Configuring dashboards and alerts in Yandex Monitoring
• Configuring responses in Yandex Cloud Logging and Yandex Cloud Functions
• Processing Yandex Audit Trails events
• Exporting audit logs to MaxPatrol SIEM
• Uploading audit logs to Splunk SIEM
• Uploading audit logs to ArcSight SIEM
• Uploading audit logs to KUMA SIEM using the management console, CLI, or API

What's nextWhat's next

• Learn more about the audit log format.
• See trail diagnostic logs.
• Learn about events.