Перейти к основному содержимому
Версия: 4.6.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>
Последнее обновление