Отправка событий

API приёма — для систем без агента и без syslog: ваших приложений и скриптов, сборщиков журналов вроде Fluent Bit и Vector, конвейеров CI, облачных журналов аудита. Компьютеры Windows используют агент, серверы Linux проверяются по SSH, а устройства, умеющие syslog, отправляют его на порт 514 — см. Подключение источников данных.

Каждый эндпоинт приёма принимает ключ API с ролью ANALYST и областью write (см. Ключи API и роли). Каждое событие проходит тот же конвейер, что и события агента: нормализацию, уровни обнаружения, дедупликацию и корреляцию.

Эндпоинты

Метод и путь	Тело	Ограничение
POST /api/ingest/event	Один JSON-объект	—
POST /api/ingest/records	JSON-массив или по одному JSON-объекту в строке — то, что отправляют Fluent Bit и Vector	5 000 записей, 10 МБ
POST /api/ingest/batch	{"events": [...], "format": "json"} — формат json, syslog или cef	5 000 событий
POST /api/ingest/syslog	{"line": "<34>1 2026-10-17T09:00:00Z web-01 sshd - - - Failed password for root"}	8 192 символа
POST /api/ingest/cef	{"line": "CEF:0|Vendor|Product|1.0|100|Port scan|7|src=203.0.113.7 dst=10.0.0.5"}	8 192 символа
POST /api/ingest/cloudtrail	{"records": [...]} или {"event": {...}} — записи AWS CloudTrail	—
POST /api/ingest/azure-monitor	{"records": [...]} или {"event": {...}}	—
POST /api/ingest/log-file	Multipart: file и fmt = syslog, cef, json (по объекту в строке) или evtx	25 МБ, 5 000 записей

Читаются строки syslog и в форме RFC 5424, и в форме RFC 3164.

JSON-событие

curl -X POST https://soc.example.com/api/ingest/event \
  -H "X-API-Key: legit_…" \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "auth_failure",
        "hostname": "web-01",
        "src_ip": "203.0.113.7",
        "message": "Failed password for root from 203.0.113.7",
        "timestamp": "2026-10-17T09:00:00Z"
      }'

Это сохраняет одну неудачную попытку входа. Само по себе это не открывает алерт: алерты открывают правила и уровни обнаружения — пять неудач с одного адреса и затем успешный вход в пределах десяти минут открывают. Событие, которое отправитель пометил как high или critical, открывает алерт само.

Парсер читает имена полей, которые уже используют большинство отправителей журналов, поэтому запись почти никогда не нужно переделывать:

Смысл	Читаемые имена полей — берётся первое найденное
Хост	hostname, host, computer, machine, agent_hostname, ComputerName, Computer, host_name
Что произошло	event_type, EventID, eventType, type, action
Важность	severity, level, SeverityName, severity_label
Сообщение	message, msg, description, event_message, log
Адрес источника	src_ip, source_ip, src, ClientIP, ipAddress, IpAddress
Адрес назначения	dst_ip, dest_ip, destination_ip, dst, DestinationIp

Поля внутри вложенного объекта raw тоже ищутся. tags и entities (строки вроде user:alice) сохраняются как переданы.

Важность — одно из info, low, medium, high, critical. Слова syslog (debug, notice, warning, error, alert, emergency) переводятся; неизвестное парсеру значение читается как medium; событие, отправленное без важности, — low. В строке syslog важность из <PRI> читается по собственной шкале syslog — от 0 (Emergency, читается как critical) до 7 (Debug, читается как info); исключение — входы, изменения привилегий и сообщения о вредоносном ПО, где важность определяет само сообщение.

Время. timestamp — время события, как его сообщает источник. Время получения сервер записывает отдельно; отправитель задать его не может.

События Windows. Объект с EventID, event_id или winlog.event_id (как отправляет Winlogbeat) разбирается как событие Windows — с тем же сопоставлением, что и события агента.

Аудит Linux. Запись auditd в message читается как auditd — так же, как через syslog.

Уже нормализованные. Событие с "schema_version": "legit.event.v1" и объектом normalized принимается как нормализованное: его поля доходят до правил как есть.

Ответ

{
  "event_id": "3eeaf0fe-60b1-46f6-9aba-edb5aa48cd81",
  "source": "web-01",
  "finding_id": null,
  "status": "ok",
  "pipeline_score": 0.0,
  "error": null
}

event_id — сохранённое событие: GET /api/events/{event_id} возвращает его. source — хост, устройство или продукт, который называет событие. finding_id заполнен, если событие подняло алерт или добавилось к открытому. pipeline_score — оценка риска этого алерта. Пакетные эндпоинты вместо этого возвращают итоги: total, processed, findings_created, errors (у каждой — index события) и duration_ms.

Когда что-то отклонено

Ответ	Что значит
status: "parse_error"	Событие не удалось прочитать. Оно хранится в очереди dead-letter (GET /api/ingest/dead-letters, ADMIN) и не теряется.
status: "pipeline_error"	Событие прочитано, но не сохранено или не оценено; error говорит почему. Отправьте его снова.
422	Строка syslog или CEF, которая ими не является, лог-файл неизвестного формата или пакет больше 5 000 событий.
413	Лог-файл больше 25 МБ.
429	Дневной лимит событий тенанта исчерпан. В теле — лимит, сколько отправлено сегодня и когда лимит обновится; Retry-After — сколько секунд ждать.

Проверьте конвейер

POST /api/ingest/test с {} проводит одно безвредное тестовое событие через весь конвейер. Проверьте так ключ и соединение, прежде чем направлять отправитель журналов в API.