--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/security/audit-log.md?version=main - https://ydb.tech/docs/ru/security/audit-log.md?version=main sourcePath: ru/core/security/audit-log.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Аудитный лог _Аудитный лог_ — это поток записей, фиксирующих работу кластера YDB. В отличие от технических логов, которые помогают в обнаружении сбоев и устранении неполадок, аудитный лог предоставляет данные значимые для безопасности. Он служит источником информации, отвечая на вопросы: кто что сделал, когда и откуда. Одна запись в аудитном логе может выглядеть так: ```json {"@timestamp":"2025-11-03T18:07:39.056211Z","@log_type":"audit","operation":"ExecuteQueryRequest","database":"/my_dir/db1","status":"SUCCESS","subject":"serviceaccount@as","remote_address":"ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]"} ``` Примеры типичных событий аудитного лога: * доступ к данным через DML-запросы; * операции управления схемой или конфигурацией; * изменения прав или настроек контроля доступа; * административные действия пользователей. Секция `audit_config` в [конфигурации кластера](https://ydb.tech/docs/ru/reference/configuration/index.md?version=main) определяет, какие аудит-логи собираются, как они сериализуются и куда доставляются. Подробнее см. в разделе [Конфигурация аудитного лога](#audit-log-configuration). ## Ключевые понятия {#audit-log-concepts} ### Аудитные события {#audit-events} _Аудитное событие_ — это запись в аудитном логе, которая фиксирует одно действие, важное для безопасности. Каждое событие содержит атрибуты, описывающие разные аспекты события. Общие атрибуты перечислены в разделе [Общие атрибуты](#common-attributes). ### Источники аудитных событий {#audit-event-sources} _Источник аудитных событий_ — это служба или подсистема YDB, которая может генерировать аудитные события. Каждый источник имеет уникальный идентификатор (UID) и может предоставлять дополнительные атрибуты, характерные для этого источника. Некоторые источники требуют дополнительной настройки, например включения [функциональных флагов](https://ydb.tech/docs/ru/reference/configuration/feature_flags.md?version=main), чтобы начать генерировать события. Подробнее см. [Обзор источников аудитных событий](#audit-event-sources-overview). ### Классы логирования {#log-classes} Аудитные события группируются в _классы логирования_, которые отражают основные категории операций. Вы можете включать или отключать запись для каждого класса в [конфигурации](#log-class-config) и при необходимости настраивать каждый класс отдельно. Доступные классы логирования: #| || **Класс логирования** | **Описание** || || `ClusterAdmin` | Запросы на администрирование кластера. || || `DatabaseAdmin` | Запросы на администрирование баз данных. || || `Login` | Запросы на вход. || || `NodeRegistration` | Регистрация нод. || || `Ddl` | DDL-запросы. || || `Dml` | DML-запросы. || || `Operations` | Асинхронные операции RPC, для отслеживания результата которых требуется опрос. || || `ExportImport` | Операции экспорта и импорта данных. || || `Acl` | Операции с ACL (списками контроля доступа). || || `AuditHeartbeat` | Синтетические heartbeat-сообщения, подтверждающие работу аудитного логирования. || || `Default` | Настройки по умолчанию для любого компонента без собственной секции конфигурации. || |# На данный момент не все источники аудитных событий группируют события по классам. Чаще всего для их записи будет достаточно [базовой конфигурации](#enabling-audit-log). Подробности см. в разделе [Обзор источников аудитных событий](#audit-event-sources-overview). ### Фазы логирования {#log-phases} Некоторые источники аудитных событий разделяют обработку запроса на этапы. _Фазы логирования_ указывают те этапы, на которых создаются события аудитного лога. Указание фаз логирования полезно, когда требуется детальная видимость выполнения запроса и нужно фиксировать события до и после критических этапов обработки. Доступные фазы логирования: #| || **Фаза логирования** | **Описание** || || `Received` | Запрос получен, выполнены начальные проверки и аутентификация. Атрибут `status` устанавливается в значение `IN-PROCESS`.
Эта фаза отключена по умолчанию; чтобы включить её, добавьте `Received` в `log_class_config.log_phase`. || || `Completed` | Запрос полностью завершён. Атрибут `status` принимает значение `SUCCESS` или `ERROR`. Эта фаза включена по умолчанию, если `log_class_config.log_phase` не задан. || |# ### Направления аудитного лога {#audit-log-destinations} _Направление аудитного лога_ — получатель потока аудитного лога. На данный момент вы можете настроить следующие направления для аудитного лога: * файл на каждой ноде кластера YDB; * агент, который доставляет метрики [Unified Agent](https://yandex.cloud/docs/monitoring/concepts/data-collection/unified-agent/); * стандартный поток ошибок `stderr`. Вы можете использовать любое из перечисленных направлений или их комбинации. Подробнее см. в разделе [Конфигурация аудитного лога](#audit-log-configuration). Если поток перенаправлен в файл, доступ к аудитному логу определяется правами файловой системы. Сохранение аудитного лога в файл рекомендуется для продуктивных инсталляций. Для тестовых инсталляций направляйте аудитный лог в стандартный поток ошибок (`stderr`). Дальнейшая обработка потока зависит от настроек [логирования](https://ydb.tech/docs/ru/devops/observability/logging.md?version=main) кластера YDB. ## Обзор источников аудитных событий {#audit-event-sources-overview} В таблице ниже приведены встроенные источники аудитных событий. Используйте её, чтобы определить, какой источник генерирует нужные события и как их включить. #| || **Источник / UID** | **Что фиксирует** | **Требования к настройке** || || [Schemeshard](#schemeshard)
`schemeshard` | Операции со схемой, изменения ACL и действия по управлению пользователями. | Входит в [базовую конфигурацию аудита](#enabling-audit-log). || || [gRPC-сервисы](#grpc-proxy)
`grpc-proxy` | Внешние gRPC-запросы YDB. | Включите соответствующие [классы логирования](#log-class-config) и при необходимости [фазы логирования](#log-phases). || || [gRPC-соединение](#grpc-connection)
`grpc-conn` | События подключения и отключения клиентов. | Включите функциональный флаг [`enable_grpc_audit`](https://ydb.tech/docs/ru/reference/configuration/feature_flags.md?version=main). || || [gRPC-аутентификация](#grpc-login)
`grpc-login` | Попытки аутентификации в gRPC. | Включите класс `Login` в [`log_class_config`](#log-class-config). || || [Сервис мониторинга](#monitoring)
`monitoring` | HTTP-запросы, обрабатываемые [эндпоинтом мониторинга](https://ydb.tech/docs/ru/reference/configuration/tls.md?version=main#http). | Включите класс `ClusterAdmin` в [`log_class_config`](#log-class-config). || || [Heartbeat](#heartbeat)
`audit` | Синтетические heartbeat-события, подтверждающие работоспособность аудитного логирования. | Включите класс `AuditHeartbeat` в [`log_class_config`](#log-class-config) и при необходимости настройте [параметры heartbeat](#heartbeat-settings). || || [BlobStorage Controller](#bsc)
`bsc` | Изменения конфигурации BlobStorage Controller из консоли. | Входит в [базовую конфигурацию аудита](#enabling-audit-log). || || [Distconf](#distconf)
`distconf` | Обновления распределённой конфигурации. | Входит в [базовую конфигурацию аудита](#enabling-audit-log). || || [Web login](#web-login)
`web-login` | Взаимодействия с виджетом аутентификации веб-консоли. | Входит в [базовую конфигурацию аудита](#enabling-audit-log). || || [Console](#console)
`console` | Операции жизненного цикла баз данных и изменения динамической конфигурации. | Входит в [базовую конфигурацию аудита](#enabling-audit-log). || |# ## Атрибуты аудитных событий {#audit-event-attributes} Атрибуты делятся на две группы: * общие атрибуты. Присутствуют в большинстве _источников аудитных событий_. Они всегда несут одинаковый смысл; * атрибуты, специфичные для _источника аудитных событий_. В этом разделе представлен справочник по атрибутам событий аудитного лога: как общим, так и специфичных для источников. Для каждого источника также указаны его UID, регистрируемые операции и требования к настройке. ### Общие атрибуты {#common-attributes} В таблице ниже перечислены общие атрибуты. #| || **Атрибут** | **Описание** || || `subject` | [SID](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#access-sid) источника события, если обязательная аутентификация включена, иначе `{none}`. || || `sanitized_token` | Частично маскированный токен аутентификации, использованный для выполнения запроса. Позволяет связывать события и при этом скрывать исходные учётные данные. Если аутентификация не выполнялась, значение будет `{none}`. || || `operation` | Название операции (например, `ALTER DATABASE`, `CREATE TABLE`). || || `component` | Уникальный идентификатор _источника аудитных событий_. || || `status` | Статус завершения операции.
Возможные значения: || || `reason` | Сообщение об ошибке. || || `request_id` | Уникальный идентификатор запроса, вызвавшего операцию. По `request_id` можно отличать события разных операций и связывать их в единый аудитный контекст. || || `remote_address` | IP-адрес клиента, отправившего запрос. || || `detailed_status` | Статус, который передаёт _источник аудитных событий_ YDB. || || `database` | Путь базы данных (например, `/my_dir/db`). || || `cloud_id` | Идентификатор облака базы данных YDB. || || `folder_id` | Идентификатор каталога кластера или базы данных YDB. || || `resource_id` | Идентификатор ресурса базы данных YDB. || |# ### Schemeshard {#schemeshard} **UID:** `schemeshard`. **Регистрируемые операции:** операции со схемой, инициированные DDL-запросами, изменения ACL и действия управления пользователями. **Как включить:** требуется только [базовая конфигурация аудита](#enabling-audit-log). Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `Schemeshard`. #| || **Атрибут** | **Описание** || || **Общие атрибуты Schemeshard** | **>** || || `tx_id` | Уникальный идентификатор транзакции. Этот идентификатор помогает различать события разных операций.
_Обязательный._ || || `paths` | Список путей в базе данных, которые изменяет операция (например, `[/my_dir/db/table-a, /my_dir/db/table-b]`).
_Необязательный._ || || **Атрибуты владения и прав доступа** | **>** || || `new_owner` | SID нового владельца объекта при передаче владения. || || `acl_add` | Список добавленных разрешений в [краткой записи](https://ydb.tech/docs/ru/security/short-access-control-notation.md?version=main) (например, `[+R:someuser]`). || || `acl_remove` | Список отозванных разрешений в [краткой записи](https://ydb.tech/docs/ru/security/short-access-control-notation.md?version=main) (например, `[-R:someuser]`). || || **Пользовательские атрибуты** | **>** || || `user_attrs_add` | Список пользовательских атрибутов, добавленных при создании объектов или обновлении атрибутов (например, `[attr_name1: A, attr_name2: B]`). || || `user_attrs_remove` | Список пользовательских атрибутов, удалённых при создании объектов или обновлении атрибутов (например, `[attr_name1, attr_name2]`). || || **Атрибуты входа/аутентификации** | **>** || || `login_user` | Имя пользователя, зафиксированное при операциях входа. || || `login_group` | Имя группы, зафиксированное при операциях входа. || || `login_member` | Изменения членства. || || `login_user_change` | Изменения, применённые к настройкам пользователя. || || `login_user_level` | Уровень привилегий пользователя, записанный в событиях аудита. Это поле принимает значение `admin`. || || **Атрибуты операций импорта/экспорта** | **>** || || `id` | Уникальный идентификатор операции экспорта или импорта. || || `uid` | Заданная пользователем метка операции. || || `start_time` | Время начала операции в формате ISO 8601. || || `end_time` | Время завершения операции в формате ISO 8601. || || `last_login` | Время последнего успешного входа пользователя в формате ISO 8601. || || **Атрибуты экспорта** | **>** || || `export_type` | Направление экспорта. Возможные значения: `yt`, `s3`. || || `export_item_count` | Количество экспортированных элементов. || || `export_yt_prefix` | Префикс пути для экспорта в YT. || || `export_s3_bucket` | Имя S3-бакета, используемого для экспорта. || || `export_s3_prefix` | Префикс пути для экспорта в S3. || || **Атрибуты импорта** | **>** || || `import_type` | Тип источника импорта. Всегда `s3`. || || `import_item_count` | Количество импортированных элементов. || || `import_s3_bucket` | Имя S3-бакета, используемого для импорта. || || `import_s3_prefix` | Префикс источника в S3. || |# ### gRPC-сервисы {#grpc-proxy} **UID:** `grpc-proxy`. **Регистрируемые операции:** все внешние (не внутренние) gRPC-запросы. **Как включить:** требуется указать классы логирования в конфигурации аудита. **Классы логирования:** зависят от типа RPC-запроса: `Ddl`, `Dml`, `Operations`, `ClusterAdmin`, `DatabaseAdmin` и другие классы. **Фазы логирования:** `Received`, `Completed`. Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `gRPC services`. #| || **Атрибут** | **Описание** || || **Общие gRPC-атрибуты** | **>** || || `grpc_method` | Имя RPC-метода.
_Необязательный._ || || `request` | Санитизированное представление входящего запроса.
_Необязательный._ || || `start_time` | Время начала операции в формате ISO 8601.
_Обязательный._ || || `end_time` | Время завершения операции в формате ISO 8601.
_Необязательный._ || || **Атрибуты транзакций** | **>** || || `tx_id` | Идентификатор транзакции. || || `begin_tx` | Флаг со значением `1`, если запрос запускает новую транзакцию. || || `commit_tx` | Показывает, завершается ли транзакция этим запросом. Возможные значения: `true`, `false`. || || **Поля запроса** | **>** || || `query_text` | Санитизированный текст [YQL](https://ydb.tech/docs/ru/yql/reference/index.md?version=main)-запроса. || || `prepared_query_id` | Идентификатор подготовленного запроса. || || `program_text` | [MiniKQL-программа](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#minikql), отправленная с запросом. || || `schema_changes` | Описание изменений схемы, запрошенных в операции. || || `table` | Полный путь таблицы. || || `row_count` | Количество строк, обработанных [пакетной вставкой данных](https://ydb.tech/docs/ru/recipes/ydb-sdk/bulk-upsert.md?version=main). || || `tablet_id` | Идентификатор таблетки. || |# ### gRPC-соединение {#grpc-connection} **UID:** `grpc-conn`. **Регистрируемые операции:** изменения состояния соединения (подключение и отключение). **Как включить:** активируйте функциональный флаг [`enable_grpc_audit`](https://ydb.tech/docs/ru/reference/configuration/feature_flags.md?version=main). _Этот источник использует только общие атрибуты._ ### gRPC-аутентификация {#grpc-login} **UID:** `grpc-login`. **Регистрируемые операции:** аутентификация в gRPC. **Как включить:** требуется указать классы логирования в [конфигурации аудита](#audit-log-configuration). **Классы логирования:** `Login`. **Фазы логирования:** `Completed`. Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `gRPC authentication`. #| || **Атрибут** | **Описание** || || `login_user` | Имя пользователя. _Обязательный._ || || `login_user_level` | Уровень привилегий пользователя, записанный в событиях аудита. Это поле принимает значение `admin`. _Необязательный._ || |# ### Сервис мониторинга {#monitoring} **UID:** `monitoring`. **Регистрируемые операции:** HTTP-запросы, обрабатываемые сервисом мониторинга. **Как включить:** требуется указать классы логирования в [конфигурации аудита](#audit-log-configuration). **Классы логирования:** `ClusterAdmin`. **Фазы логирования:** `Received`, `Completed`. Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `Monitoring service`. #| || **Атрибут** | **Описание** || || `method` | HTTP-метод запроса, например `POST`, `GET`.
_Обязательный._ || || `url` | Путь запроса без параметров строки запроса.
_Обязательный._ || || `params` | Параметры строки запроса в исходном виде.
_Необязательный._ || || `body` | Тело запроса (усечено до 2 МБ с добавлением суффикса `TRUNCATED_BY_YDB`).
_Необязательный._ || |# ### Heartbeat {#heartbeat} **UID:** `audit`. **Регистрируемые операции:** периодические [heartbeat-сообщения](#heartbeat-settings) аудита. **Как включить:** укажите классы логирования в [конфигурации аудита](#audit-log-configuration). **Классы логирования:** `AuditHeartbeat`. **Фазы логирования:** `Completed`. Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `Heartbeat`. #| || **Атрибут** | **Описание** || || `node_id` | Идентификатор ноды, на которой произошло событие. _Обязательный._ || |# ### BlobStorage Controller {#bsc} **UID:** `bsc`. **Регистрируемые операции:** запросы замены конфигурации (`TEvControllerReplaceConfigRequest`), отправляемые консолью. **Как включить:** требуется только [базовая конфигурация аудита](#enabling-audit-log). Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `BlobStorage Controller`. #| || **Атрибут** | **Описание** || || `old_config` | Снапшот предыдущей конфигурации BlobStorage Controller в формате YAML.
_Необязательный._ || || `new_config` | Снапшот конфигурации, которая заменила предыдущую.
_Необязательный._ || |# ### Distconf {#distconf} **UID:** `distconf`. **Регистрируемые операции:** изменения распределённой конфигурации. **Как включить:** требуется только [базовая конфигурация аудита](#enabling-audit-log). Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `Distconf`. #| || **Атрибут** | **Описание** || || `old_config` | Снапшот конфигурации, которая была активна до принятия распределённого обновления. Distconf сериализует его в YAML. _Обязательный._ || || `new_config` | Снапшот конфигурации, который Distconf зафиксировал после изменения. _Обязательный._ || |# ### Web login {#web-login} **UID:** `web-login`. **Регистрируемые операции:** отслеживает взаимодействия с виджетом аутентификации веб-консоли YDB. **Как включить:** требуется только [базовая конфигурация аудита](#enabling-audit-log). _Этот источник использует только общие атрибуты._ ### Console {#console} **UID:** `console`. **Регистрируемые операции:** операции жизненного цикла баз данных и изменения динамической конфигурации. **Как включить:** требуется только [базовая конфигурация аудита](#enabling-audit-log). Таблица ниже перечисляет дополнительные атрибуты, специфичные для источника `Console`. #| || **Атрибут** | **Описание** || || `old_config` | Снапшот конфигурации, которая действовала до применения запроса из консоли. _Необязательный._ || || `new_config` | Снапшот конфигурации, применённой консолью. _Необязательный._ || |# ## Конфигурация аудитного лога {#audit-log-configuration} ### Включение аудитного лога {#enabling-audit-log} Аудитное логирование работает на уровне всего кластера. Для _базовой конфигурации_ добавьте раздел `audit_config` в [конфигурацию кластера](https://ydb.tech/docs/ru/reference/configuration/index.md?version=main) и укажите одно или несколько направлений потока (`file_backend`, `unified_agent_backend`, `stderr_backend`): ```yaml audit_config: file_backend: format: audit_log_format file_path: "path_to_log_file" unified_agent_backend: format: audit_log_format log_name: session_meta_log_name stderr_backend: format: audit_log_format ``` ### Параметры audit_config {#audit-config} Все поля являются необязательными. #| || **Ключ** | **Описание** || || `stderr_backend` | Перенаправляет аудитный лог в стандартный поток ошибок (`stderr`). Для тестовых инсталляций направляйте аудитный лог в стандартный поток ошибок (`stderr`). Дальнейшая обработка потока зависит от настроек [логирования](https://ydb.tech/docs/ru/devops/observability/logging.md?version=main) кластера YDB. См. структуру [настроек backend](#backend-settings). || || `file_backend` | Записывает аудитный лог в файл на каждой ноде кластера. Если поток перенаправлен в файл, доступ к аудитному логу определяется правами файловой системы. Сохранение аудитного лога в файл рекомендуется для продуктовых инсталляций. См. структуру [настроек backend](#backend-settings). || || `unified_agent_backend` | Отправляет аудитный лог в Unified Agent. Дополнительно необходимо задать секцию `uaclient_config` в [конфигурации кластера](https://ydb.tech/docs/ru/reference/configuration/index.md?version=main). См. структуру [настроек backend](#backend-settings). || || `log_class_config` | Массив правил аудита для разных классов логирования. См. [конфигурацию классов логирования](#log-class-config). || || `heartbeat` | Необязательная конфигурация heartbeat. См. [настройки heartbeat](#heartbeat-settings). || |# ### Конфигурация направлений {#backend-settings} Каждое направление поддерживает следующие поля: #| || **Поле** | **Описание** || || `format` | Формат аудитного лога. Значение по умолчанию — `JSON`. Подробнее см. раздел [Формат логов](#log-format).
_Необязательный._ || || `file_path` | Путь к файлу, в который будет записываться аудитный лог. Если путь или файл отсутствуют, они будут созданы на каждой ноде при запуске кластера. Если файл существует, данные будут дозаписываться. Только для `file_backend`.
_Обязательный._ || || `log_name` | Метаданные сессии, передаваемые вместе с сообщением. По ним можно перенаправлять поток логов в один или несколько дочерних каналов с условием `_log_name: "session_meta_log_name"`. Только для `unified_agent_backend`.
_Необязательный._ || || `log_json_envelope` | Шаблон JSON, который оборачивает каждую запись лога. Шаблон должен содержать плейсхолдер `%message%`, заменяемый сериализованной аудитной записью. См. раздел [Формат конверта](#envelope-format).
_Необязательный._ || |# #### Формат логов {#log-format} Поле `format` определяет формат сериализации аудитных событий. Поддерживаются следующие форматы: #| || **Формат** | **Описание** || || `JSON` | Каждое аудитное событие сериализуется в однострочный JSON-объект с префиксом из временной метки в формате ISO 8601.
Пример: `