Перейти к основному содержимому
Версия: 4.5.X

xml

Плагин xml входит в состав YAML-плагинов processors и используется для нормализации событий в формате XML (подобно тому, как это делает плагин json по отношению к формату json).

Для поиска нужных элементов в XML плагин использует выражения XPath (синтаксис, также можно найти в прочих источниках). Для реализации плагина использовалась библиотека xpath для Go, поэтому не все возможности XPath могут быть покрыты, но подавляющее большинство случаев должно ею удовлетворяться.

Плагин поддерживает эвристический анализ.

Конфигурация​

Конфигурация плагина xml состоит из списка паттернов извлечения полей события. Каждый паттерн содержит следующие поля:

  • expr — выражение XPath для поиска нужного узла (узлов) XML-документа
  • from — поле исходного события, к которому применяется паттерн. Если не указано, паттерн применяется к исходному тексту Raw
  • to — поле события, в которое помещается результат извлечения
  • value-type — тип поля, в которое помещается результат извлечения. Если не указано, используется тип string. Если поле события, куда помещается результат (см. поле конфигурации to), соответствует какому-либо предзагруженному, то его тип используется независимо от значения этого поля

Примеры​

Извлечение текста из полей XML​

Предположим, у нас имеется следующий XML-документ:

<Event>
    <ID>1</ID>
    <Timestamp>2024-06-28T06:49:14Z</Timestamp>
    <Data>event data</Data>
</Event>

Для извлечения всех текстов в поля можно использовать следующую конфигурацию:

processors:
- module: xml
  patterns:
  - expr: /Event/Data/text()
    to: ECS.Base.Message
  - expr: /Event/ID/text()
    to: ECS.Event.ID
  - expr: /Event/Timestamp/text()
    to: ECS.Base.Timestamp

Важно добавлять в конце выражения функцию text, иначе плагин извлечет узел целиком (например, вместо event data будет <Data>event data</Data>).

Извлечение атрибутов​

Улучшим документ из прошлого примера и добавим в него атрибуты:

<Event provider="provider-name">
    <ID format="integer">1</ID>
    <Timestamp>2024-06-28T06:49:14Z</Timestamp>
    <Data>event data</Data>
</Event>

Дополним конфиг из предыдущего примера паттернами извлечения атрибутов:

processors:
- module: xml
  patterns:
  - expr: /Event/Data/text()
    to: ECS.Base.Message
  - expr: /Event/ID/text()
    to: ECS.Event.ID
  - expr: /Event/Timestamp/text()
    to: ECS.Base.Timestamp
  - expr: /Event/@provider
    to: ECS.Event.Provider
  - expr: /Event/ID/@format
    to: Event.ID.Format

Извлечение с фильтрацией​

Чтобы показать извлечение с использованием фильтрации в XPath, добавим в документ поле, содержащее либо IP-адрес источника, либо его доменное имя. На тип поля (IP или домен) будет указывать атрибут.

<Event provider="provider-name">
    <ID format="integer">1</ID>
    <Timestamp>2024-06-28T06:49:14Z</Timestamp>
    <Data>event data</Data>
    <SourceHost type="ip">127.0.0.1</SourceHost>
</Event>

Чтобы извлекать поле либо в ECS.Source.IP, либо в ECS.Source.Domain, нужно написать два паттерна для этих двух случаев с фильтрацией. Также в любом случае мы извлекаем поле в ECS.Source.Address, так что добавляется и третий паттерн:

processors:
- module: xml
  patterns:
  - expr: /Event/Data/text()
    to: ECS.Base.Message
  - expr: /Event/ID/text()
    to: ECS.Event.ID
  - expr: /Event/Timestamp/text()
    to: ECS.Base.Timestamp
  - expr: /Event/@provider
    to: ECS.Event.Provider
  - expr: /Event/ID/@format
    to: Event.ID.Format
  - expr: /Event/SourceHost/text()
    to: ECS.Source.Address
  - expr: /Event/SourceHost[@type="ip"]/text()
    to: ECS.Source.IP
  - expr: /Event/SourceHost[@type="domain"]/text()
    to: ECS.Source.Domain

После применения к событию плагина, получаем в событии поле ECS.Source.IP со значением 127.0.0.1. Чтобы проверить случай с доменом, можно слегка изменить событие:

<Event provider="provider-name">
    <ID format="integer">1</ID>
    <Timestamp>2024-06-28T06:49:14Z</Timestamp>
    <Data>event data</Data>
    <SourceHost type="domain">localhost</SourceHost>
</Event>
Последнее обновление