Миграция на ECS
ECS (Elastic Common Schema) - спецификация, разработанная сообществом пользователей Elastic. ECS определяет общий набор полей при хранении данные о событиях в OpenSearch.
Использование ECS позволяет:
- нормализовать свои данные о событиях для последующего анализа и визуализа ции этих данных, представленных в событиях
- унифицировать данные для уменьшения трудозатрат в дальнейшем (максимизация совместимости и повторное использование, например, использование разработанных дашбордов со стороны без дополнительной адаптации)
- ускорение работы OpenSearch в целом за счёт правильного распределения типов данных каждому полю
Подробнее можно узнать в официальной документации. Все описанное ниже актуально для версии 8.6.0.
В данном руководстве рассматривается версия ECS 8.6.0. В Logstash 8.х версии ECS включен по умолчанию и соответствует версии v8, но вы можете при необходимости отключить данную функцию. При использовании версии 7.x по умолчанию ECS отключен, допускается использование версии v1. При обновлении до актуальной версии не рекомендуется выставлять режим v1, так как возможен конфликт именования полей который встроен в версии v8, в таком случае конвейер Logstash не запустится.
Уровни поля ECS
В ECS поля можно разделить на:
- базовые (основные) (core fields) - относятся поля, которые подходят для любого источника данных. Например, @timestamp, tags, message и другие. В первую очередь требуется заполнять именно эти поля.
- дополнительные - относятся остальные поля, чаще используются в более узких вариантах или могут быть открытыми в интерпретации. Есть вероятность, что в будущем могут быть изменены
Соглашения и правила ECS
Общие соглашения
- Для типа данных integer(целые числа) в рамках ECS использовать тип long
- для полей ID и кодов (например, код ошибки) использовать тип keyword
- для текстового поля или мульти-поля
- соглашение по умолчанию для Elasticsearch для текстовых полей, поле text индексируется дважды:
- соглашение для ECS меняет подход, почти все текстовые поля имеют тип keyword за некоторым исключением. Если требуется полнотекстовый поиск, то допускается добавить мульти-поле (multi-field)
- поля исключения, которые должны индексироваться для полнотекстового поиска
Шаблоны реализации
- Base fields - базовые поля, группа индивидуальных полей верхнего уровня за пределами набора
- host - содержит различные поля, относящиеся к устройству где произошло событие, может быть компьютером, виртуальной машиной, контейнером или облачным сервером
- Agent и observer - агент и наблюдатель. Агент - это ПО, которое собирает, наблюдает, измеряет или обнаруживает событие. Примером агента является ElasticBeat. Наблюдателем является внешний мониторинг или устройство-посредник, например, firewall, APM server, web proxy.
- Timestamp - каждое событие должно иметь временную метку, некоторые события также имеют дополнительные временные метки, следующие хронологическому порядку @timestamp < event.created < event.ingested:
- Origin - определённые поля для фиксации места возникновения события
- Categorization - классификация полей ECS (подробнее смотрите ниже)
- Enrichting events - наполнение событий дополнительной информацией, в ECS есть много таких полей, которые можно добавить к событию
- Lookups
- Parsing
- Related fields - связанные поля. Многие события имеют различные поля с идентичным содержимым, например, IP адрес, hash файла, имя хоста. Для обращения к таким полям используйте related.* поля, например, если для некоторого события IP есть в полях host.*, source.*, destination.*, добавьте все адреса в поле related.ip для удобства дальнейшего поиска
Обработка сетевых событий
Здесь расположены рекомендации по обработке событий, связанных с сетью. Подробнее можно посмотреть на официальной странице документации.
- Проверка наличия источника и назначения - если событие содержит информацию об источнике и принимающей стороне, то эти поля (source.* и destination.*) заполняются в первую очередь. Некоторые события могут указывать на роли каждого хоста (client и server), их стоит заполнять дополнительно к полям источника и назначения, т.е. поля из source.*/destination.* должны быть скопированы в client.*/server.*. Это важно заполнять для дальнейшей фильтрации по ролям или по источнику/назначению.
- Заполняйте связанные поля, все IP адреса добавляйте в поле related.ip в качестве массива, также в сетевых событиях могут встречаться имена хостов, их тоже надо скопировать в related.hosts
- Заполните поля категоризации, которые лучше всего характеризуют событие
- Сочетание полей категоризации "event.category: network" и "event.type: protocol" требуют заполнения также поля network.protocol
- при желании исходные поля можно сохранить как custom поля, например, для NGINX - Nginx.*
Принципы проектирования ECS
- Общая схема - главная цель ECS это максимизировать совместимость и повторное использование
- Поля устанавливают наборы имён - старайтесь разбить сложные концепции на более простые, например, dns.question.class, dns.question.answer, dns.question.type
- Согласованность наименования - не ограничивайте термины с широким значением одним случаем, например:
- Повторное использование
- Custom fields - пользовательские поля во многих ситуациях потребуется создавать для полного описания события, но добавляйте их только если отсутствует соответствующее поле в концепции ECS
Рекомендации по названию полей
Если Вы не нашли соответствующее поле в ECS, то можно использовать произвольное поле, но оно должно соответствовать следующим правилам:
- имя поля должно быть в нижнем регистре (за исключением пользовательских - custom)
- для комбинирования слов использовать нижнее подчёркивание (например, requests_per_sec)
- не использовать никакие спецсимволы, кроме нижнего подчёркивания
- используйте настоящее время, если поле не описывает уже свершившийся факт
- правильно используйте единственное и множественное число, чтобы отразить содержимое поля (например, requests_per_sec или request_per_sec)
- используйте префиксы для всех полей, т.е. все поля, относящиеся к host должны быть помещены в hosts.xxx
- для самих полей используйте именно объекты JSON, т.е. использовать "точку" (подробнее можно прочитать на официальной странице документации)
- организуйте поля от общего к частному
- не стоит использовать повторения слов (например, вот так не правильно: host.host_ip, лучше использовать host.ip)
- избегайте сокращений за исключением общепринятых (например, ip, geo и др.)
- для пользовательского поля (custom field), если не найдено соответствие в предопределённых полях, рекомендуется написать название сервиса с большой буквы (нами выбран такой способ для разделения предопределённых полей ECS и custom полями) и уже в него разместить все остальные поля. Например, Nginx.source.ip, Jitsi.ip. Если пренебречь этим правилом, то в дальнейшем может быть ситуация, когда будет зарезервировано поле в ECS и его имя совпадёт с названием вашего пользовательского поля
Поля классификации ECS
ECS предоставляет 4 уровня категоризации для общего описания независимо от источника событий. Для начала рассмотрите основные принципы классификации:
- похожие события, которые можно рассматривать и анализировать вместе должны попадать в одно поле event.category
- event.category и event.type являются массивами, поэтому старайтесь отнести событие ко всем относящимся категориям
- должны использоваться только предопределённые значения, описанные ниже
- event.outcome очень ограничен для использования результата события, действия зависящие от предметной области, например, запрет или разрешение, которые могут считаться результатами, должны фиксироваться в полях event.type и/или event.action, например, событие блокировки доступа, со стороны сетевого экрана событие успешно (event.outcome: success), но сам результат выполнения - отброшен (event.action: dropped)
- значения event.category, event.type, event.outcome одинаковы для всех значений event.kind
- если конкретное событие не соответствует ни одному из предопределённых значений классификации, поле следует оставить пустым
Рассмотрим 4 уровня классификации, представленные в виде поля, более детально.