> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Журналы аудита и интеграция с SIEM

> Передавайте структурированный поток событий аудита Yahont в SIEM для мониторинга безопасности и соответствия требованиям

## Обзор

Yahont формирует нормализованный структурированный **поток событий аудита** для действий, важных для безопасности:
аутентификации, изменений пользователей и управления доступом,
изменений административной конфигурации и доступа к учётным данным. Каждое событие — один объект JSON,
поэтому поток можно передать в любой SIEM — **Splunk, Microsoft Sentinel, Elastic, Google Chronicle,
AWS Security Lake** — без разработки интеграции на стороне Yahont.
Вы направляете свой сборщик журналов на журналы Yahont, фильтруете поток аудита и разбираете JSON.

Имена полей и таксономия действий построены по образцу [**OCSF**](https://schema.ocsf.io)
(Open Cybersecurity Schema Framework), поэтому события легко сопоставляются с классами событий,
которые уже понимает большинство SIEM.

## Что фиксируется

> **Аутентификация**
>
> Успешный вход, неудачный вход, выход, регистрация, запрос восстановления пароля,
> сброс пароля и подтверждение адреса электронной почты.

> **Пользователи и управление доступом**
>
> Создание пользователей (приглашения администратором), удаление, деактивация, реактивация,
> изменение ролей и изменение состава групп пользователей.

> **Конфигурация и ресурсы**
>
> Создание, изменение и удаление поставщиков LLM, коннекторов, пар «коннектор — учётные данные»,
> API-ключей и учётных данных, а также события доступа к учётным данным (расшифровки).

Каждое событие фиксирует, **кто** что **сделал**, с **каким ресурсом**, **когда**,
**откуда** и **успешно** ли — основу журнала аудита.

## Как это работает

События аудита записываются как записи `INFO` в отдельный логгер **`onyx.audit`**.
Тело каждой записи — один объект JSON; Yahont сам сериализует событие,
поэтому строка аудита одинакова независимо от формата ваших журналов.

Отправка событий **безопасна при сбоях**: она никогда не прерывает запрос пользователя или запуск коннектора,
даже если сбор контекста или запись в журнал не удались.
События с большим объёмом дедуплицируются в течение короткого (10 минут) окна с помощью Redis.
Дедупликация **открыта при сбое** (fail-open): если Redis недоступен, проверка дедупликации пропускается,
а событие всё равно отправляется,
поэтому событие аудита никогда не теряется молча из-за проблем с инфраструктурой (в худшем случае вы увидите дубликат).

Подсистема **всегда включена** — нет флага включения и выключения, настройки формата вывода или места назначения,
а окно дедупликации фиксировано. Единственная связанная настройка — `LOG_FORMAT` (ниже),
которая определяет вид *окружающих* записей журнала; тело JSON аудита в любом случае одинаково.

> [!TIP]
>
> Запускайте Yahont с `LOG_FORMAT=json`, чтобы *все* записи журнала, а не только события аудита,
> были пригодны для машинного разбора, а контекст запроса и тенанта выносился в поля верхнего уровня.
> Это значительно упрощает фильтрацию и разбор в вашем сборщике.

## Схема события

| Поле | Тип | Описание |
| - | - | - |
| `audit_schema_version` | string | Версия схемы (сейчас `"1.0"`). |
| `ts` | number | Время события, секунды эпохи. |
| `action` | string | Значение таксономии действий, `<домен>.<глагол>` (например, `llm_provider.update`). Стабильное, только дополняется. |
| `ocsf_class` | string | `authentication`, `account_change` или `api_activity`. |
| `outcome` | string | `success`, `failure` или `denied`. |
| `tenant_id` | string \| null | Тенант, в котором произошло действие. |
| `actor` | object \| null | `{ user_id, email, api_key_id, auth_type }`. Никогда не содержит секретов. |
| `resource_type` | string \| null | Тип затронутого ресурса (например, `llm_provider`, `user`, `api_key`). |
| `resource_id` | string \| null | Идентификатор затронутого ресурса. |
| `request_id` | string \| null | Связывает событие с остальными журналами этого запроса. |
| `endpoint` | string \| null | Маршрут, породивший событие. |
| `source_ip` | string \| null | IP клиента (из `X-Forwarded-For`). |
| `extra` | object \| null | Дополнительный контекст без секретов. |

Значения `action` — стабильный контракт, который только дополняется: по ним безопасно фильтровать и строить панели.
Со временем могут добавляться новые действия; существующие не меняют значения.

### Пример события

```json theme={null}
{
  "audit_schema_version": "1.0",
  "ts": 1750000000.123,
  "action": "llm_provider.update",
  "ocsf_class": "api_activity",
  "outcome": "success",
  "tenant_id": "tenant_abc",
  "actor": { "user_id": "u-42", "email": "admin@example.com", "api_key_id": null, "auth_type": "oauth" },
  "resource_type": "llm_provider",
  "resource_id": "7",
  "request_id": "01J...",
  "endpoint": "PUT /admin/llm/provider",
  "source_ip": "203.0.113.5",
  "extra": null
}
```

## Передача в SIEM

Поскольку события аудита — это просто строки журнала JSON с известным префиксом логгера,
подойдёт любой сборщик журналов.

**1. Запустите Yahont с журналированием в JSON**

Задайте `LOG_FORMAT=json`, чтобы каждая запись журнала была структурирована и содержала поля `logger` и `message`.

**2. Передавайте журналы Yahont**

Направьте Fluent Bit, Vector, агент CloudWatch,
Filebeat или ваш существующий сборщик на stdout контейнера Yahont (или на примонтированные файлы журналов).

**3. Выделите и разберите поток аудита**

Оставьте только записи, у которых `logger` начинается с `onyx.audit`,
затем разберите поле `message` каждой записи как JSON, чтобы получить поля события, описанные выше.

**4. Направьте в SIEM**

Отправьте разобранные события на конечную точку приёма вашего SIEM.
Поля в формате OCSF сопоставляются с классами событий «Аутентификация», «Изменение аккаунта» и «Активность API».

### Примеры сборщиков

```toml Vector theme={null}
# Keep only audit records, then replace the event with the parsed JSON payload.
[transforms.onyx_audit]
type = "filter"
inputs = ["onyx_logs"]
condition = '''starts_with(string!(.logger), "onyx.audit")'''

[transforms.onyx_audit_parsed]
type = "remap"
inputs = ["onyx_audit"]
source = '. = parse_json!(.message)'
```

```ini Fluent Bit theme={null}
# Match the audit stream by logger prefix.
[FILTER]
  Name    grep
  Match   onyx.*
  Regex   logger ^onyx\.audit
```

> [!NOTE]
>
> Фильтруйте по **префиксу** `onyx.audit`, чтобы захватить всё.
> Поток также разделён на дочерние логгеры по классам — `onyx.audit.authentication`, `onyx.audit.account_change`,
> `onyx.audit.api_activity` и `onyx.audit.credential_access` — если нужно направлять классы в разные места назначения.

## Справочник событий

Каждое значение `action`, что его вызывает, и поля, наиболее полезные для правил обнаружения в SIEM. `actor`,
`tenant_id`, `request_id`, `endpoint`, `source_ip` и `outcome` присутствуют в каждом событии (см.
[Схему события](#event-schema)) и в таблицах ниже опущены.

### Аутентификация

`ocsf_class: authentication`

| `action` | Срабатывает, когда | Примечания |
| - | - | - |
| `auth.login` | Пользователь успешно входит | |
| `auth.login_failure` | Попытка входа не удалась | `outcome` равен `failure` или `denied` для неинтерактивного входа |
| `auth.logout` | Пользователь выходит | |
| `auth.register` | Регистрируется новый аккаунт (саморегистрация) | |
| `auth.password_forgot` | Запрошено письмо для сброса пароля | |
| `auth.password_reset` | Сброс пароля завершён | |
| `auth.email_verify` | Запрошено письмо для подтверждения адреса электронной почты | |

### Пользователи и управление доступом

`ocsf_class: account_change` — `resource_type` равен `user` (или `user_group`).

| `action` | Срабатывает, когда | `resource_id` | Ключевые поля `extra` |
| - | - | - | - |
| `user.create` | Администратор приглашает новых пользователей | — | `invited_emails` |
| `user.delete` | Пользователь удалён | id пользователя | `target_email` |
| `user.deactivate` | Пользователь деактивирован | id пользователя | `target_email` |
| `user.reactivate` | Пользователь реактивирован | id пользователя | `target_email` |
| `user.role_change` | Роль пользователя изменена | id пользователя | `target_email`, `old_role`, `new_role` |
| `user.group_change` | Изменён состав группы пользователей | id группы пользователей | `added_user_ids`, `removed_user_ids` |

### Конфигурация и ресурсы

`ocsf_class: api_activity`

| `action` | Срабатывает, когда | `resource_type` | `resource_id` | Ключевые поля `extra` |
| - | - | - | - | - |
| `llm_provider.create` / `.update` / `.delete` | Поставщик LLM создан, изменён или удалён | `llm_provider` | id поставщика | |
| `connector.create` / `.update` / `.delete` | Коннектор создан, изменён или удалён | `connector` | id коннектора | `source` (при создании) |
| `cc_pair.create` / `.update` / `.delete` | Коннектор связан с учётными данными, изменился его статус или связь удалена | `cc_pair` | id пары «коннектор — учётные данные» | `connector_id`, `credential_id`; `status` (при изменении) |
| `api_key.create` / `.regenerate` / `.delete` | API-ключ создан, перевыпущен или отозван | `api_key` | id API-ключа | |
| `credential.create` / `.update` / `.delete` | Сохранённые учётные данные созданы, изменены или удалены | `credential` | id учётных данных | `source` (при создании) |
| `credential.access` | Сохранённые учётные данные расшифрованы для использования | — | — | Отправляется по **другой схеме** — см. [Доступ к учётным данным](#credential-access) ниже |

### Доступ к учётным данным

`onyx.audit.credential_access`

События расшифровки учётных данных появились до обобщённой схемы и отправляются в **плоском устаревшем наборе полей**
для обратной совместимости.
Они используют то же дерево логгеров `onyx.audit` и то же поведение «безопасно при сбоях» и «открыто при сбое»,
но **не** содержат полей обобщённой схемы: нет `action`, `ocsf_class`, `outcome`, `resource_type`/`resource_id`,
`extra` и вложенного объекта `actor`, а IP клиента называется `client_ip` (а не `source_ip`).
Разбирайте этот поток отдельно; правила обнаружения, написанные для обобщённой схемы, к нему не подойдут.

| Поле | Тип | Описание |
| - | - | - |
| `ts` | number | Время события, секунды эпохи. |
| `tenant_id` | string \| null | Тенант, в котором произошла расшифровка. |
| `credential_type` | string | Общая категория, например `llm_provider` или `connector`. |
| `provider` | string \| null | Название поставщика или источника, если известно (например, `openai`, `google_drive`). |
| `row_id` | number \| null | ID строки учётных данных или поставщика LLM в БД. |
| `user_id` | string \| null | ID действовавшего пользователя, если доступен (для фоновых заданий может быть null). |
| `auth_type` | string \| null | Как действующее лицо аутентифицировалось, если известно. |
| `request_id` | string \| null | Связывает с остальными журналами этого запроса. |
| `endpoint` | string \| null | Маршрут, породивший событие. |
| `client_ip` | string \| null | IP клиента (из `X-Forwarded-For`). |

> [!TIP]
>
> Таксономия **только дополняется**: в будущих релизах могут появляться новые значения `action`,
> но существующие никогда не меняют значения, поэтому правила обнаружения и панели, построенные на этих значениях,
> продолжают работать после обновлений.

## Примечания

* **Секреты никогда не записываются в журнал.** Объекты actor и контекст `extra` по замыслу очищаются
  от значений учётных данных.
* **События доступа к учётным данным** (`onyx.audit.credential_access`) используют отдельный
  плоский набор полей, отличный от обобщённой схемы, для обратной совместимости — полный список полей см.
  в разделе [Доступ к учётным данным](#credential-access).
  Они используют то же дерево логгеров и то же поведение безопасности при сбоях.
* Для развёртываний **Yahont Cloud** (мультитенантных) пересылка журналов аудита организована
  иначе, так как вы не управляете конвейером журналов — [свяжитесь с нами](/security/contact_us),
  чтобы обсудить варианты доставки в SIEM.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.