Decoders Syntax

decoder

The attributes listed below define a decoder.

Example:

Set name of decoder to ossec:

<decoder name="ossec">
  ...
</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 what we call sibling decoders, which is a handy decoding strategy to handle dynamic logs.

Example:

Decoder_junior will enter only if decoder_parent has previously matched.

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

accumulate

Allows ThreatLockDown to track events over multiple log messages based on a decoded id.

program_name

It 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 will be used.

Example:

Define that the decoder is related with the test, TEST or equivalent (case-insensitive) process:

<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's 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.

The attributes below are optional.

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 will be used.

regex

Regular expressions or regex are sequences of characters that define a pattern. Decoders use them to find words or other patterns into the rules. 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 label requires a prematch or a program_name label defined on the same decoder or a parent with a prematch or a program_name defined label defined on it.

The attributes below are optional.

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 will be used.

Example:

Show 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.

fts

It is used to designate a decoder as one in which the first time it matches the administrator would like to be alerted.

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 may be used in any place of the same file.

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>