Decoders Syntax

decoder

The decoder option serves as the root element of a decoder file in Wazuh. It encapsulates the definition of a decoder, including its name, type, and the specific attributes that dictate how it processes and extracts information from log messages.

The attributes listed below define a decoder.

Example:

Below is a custom JSON decoder that extracts specific fields from a log message.

<decoder name="json_custom_decoder">
  <type>json</type>
  <program_name>application_logs</program_name>
  <regex>"message": "(.*?)"</regex>
  <order>message_content</order>
  <plugin_decoder>JSON_Decoder</plugin_decoder>
</decoder>

parent

It is used to link a subordinate decoder to its parent. A parent decoder can have many child decoders but take into account that a child decoder cannot be a parent. It is possible to create sibling decoders, which is a handy decoding strategy to handle dynamic logs.

Example:

decoder_junior will trigger only if decoder_father has previously matched.

<decoder name="decoder_junior">
  <parent>decoder_father</parent>
  ...
</decoder>

accumulate

Allows Wazuh to track events over multiple log messages based on a decoded id. This is particularly useful for logs that span multiple lines or entries.

program_name

This defines the program name that must be found in the log header to apply the decoder. The pre-decoding phase extracts the program name from input logs with Syslog-like headers.

The attributes below are optional.

If program_name label is declared multiple times within the decoder, the following rules apply:

• The resulting value is their concatenation.

• The resulting value of type attribute corresponds to the one specified in the last label. If it is not specified, the default value is used.

Example:

The decoder below uses the PCRE2 regular expression to match a program name called test, TEST or their equivalent (case-insensitive) in a log message:

<decoder name="test_decoder">
  <program_name type="pcre2">(?i)test</program_name>
  ...
</decoder>

prematch

Defines a regular expression that the log must match to apply the decoder. It is important to be as specific as possible to avoid matching unwanted events. Note that if the log is Syslog-like, then prematch only analyzes the log after the Syslog-like header. If the log is not Syslog-like, then it analyzes the entire log.

You can use the optional attributes below with the prematch option.

If prematch label is declared multiple times within the decoder, the following rules apply:

• The resulting value is their concatenation.

• The resulting value of type attribute corresponds to the one specified in the last label. If it is not specified, the default value is used.

regex

Regular expressions are sequences of characters that define a pattern. Decoders use them to find words or other patterns within log messages. The decoder will only extract those fields that are contained within parentheses.

An example is this regex that matches any numeral:

<regex> [+-]?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)? </regex>

When using the regex label, it is mandatory to define an order label as well. Besides, regex labels require a prematch or a program_name label defined on the same decoder or a parent with a prematch or a program_name label defined on it.

You can use the optional attributes below with the regex option.

If regex label is declared multiple times within the decoder, the following rules apply:

• The resulting value is their concatenation.

• The resulting value of the type attribute corresponds to the one specified in the last label. If it is not specified, the default value is used.

Example:

The decoder below matches a log message indicating when a user executed the sudo command for the first time:

<decoder name="sudo-fields">
  <parent>sudo</parent>
  <prematch>\s</prematch>
  <regex>^\s*(\S+)\s*:</regex>
  <order>srcuser</order>
  <fts>name,srcuser,location</fts>
  <ftscomment>First time user executed the sudo command</ftscomment>
</decoder>

order

It defines what the parenthesis groups contain and the order in which they were received. It requires a regex label defined on the same decoder. It can contain both static fields and dynamic fields.

fts

It specifies a decoder that triggers an alert the first time it matches.

Example:

The following decoder will extract the user who generated the alert and the location from where it comes:

<decoder name="fts-decoder">
  <fts>srcuser, location</fts>
  ...
</decoder>

The decoder will consider this option if the decoded event triggers a rule that uses if_fts.

ftscomment

It adds a comment to a decoder when <fts> tag is used.

plugin_decoder

Use a specific plugin decoder to decode the incoming fields. It is useful for particular cases where it would be tricky to extract the fields by using regexes.

The attribute below is optional; it allows to start the decode process after a particular point of the log.

An example of its use is described at the JSON decoder section.

use_own_name

Allows setting the name of the child decoder from the name attribute instead of using the name of the parent decoder.

json_null_field

Specifies how to treat the NULL fields coming from the JSON events. Only for the JSON decoder.

json_array_structure

Specifies how to treat the array structures coming from the JSON events. Only for the JSON decoder.

var

Defines a variable that can be used in any decoder within the same decoder file. It must be defined at the beginning of the decoder file and not inside a tagged section.

Example:

<var name="header">myprog</var>
<var name="offset">after_parent</var>
<var name="type">syscall</var>

<decoder name="syscall">
  <prematch>^$header</prematch>
</decoder>

<decoder name="syscall-child">
  <parent>syscall</parent>
  <prematch offset="$offset">^: $type </prematch>
  <regex offset="after_prematch">(\S+)</regex>
  <order>syscall</order>
</decoder>

type

It sets the type of log that the decoder is going to match.

Example:

Set type of decoder to syslog:

<decoder>
  <type>syslog</type>
  ...
</decoder>