The generic module | The Orchids IDS

The generic module is a dissection module: its purpose is to take an Orchids event, parse one of its text fields and return a refined Orchids events, with additional fields. Typically, the generic module is meant to dissect text coming from the syslog module.

The generic module is however very special. In a sense, it is a meta-module, one that allows you to define new, so-called virtual modules, whose parsing methods are defined by regular expressions.

We explain how that works on an example. The syslog module may have to dissect messages such as:

Jan 27 11:32:06 laramie dhclient: DHCPREQUEST on eth0 to 192.168.30.1 port 67

In that case, it will produce a last field .syslog.msg equal to the block of text "DHCPREQUEST on eth0 to 192.168.30.1 port 67". We would like to dissect that further.
The generic module allows you to do that, based on regular expressions.

First, one should plug the generic module so that it dissects that kind of message. The generic module defines a so-called virtual module called dhclient and which does just that. We shall describe it below. The plugging is done by the following line in $OCONF/orchids-inputs.conf, instructing Orchids to let the dhclient virtual module parse the last field, .syslog.msg (in the example, "DHCPREQUEST on eth0 to 192.168.30.1 port 67"), provided by the syslog module, on the condition that its next-to-last field, .syslog.prog, is equal to "dhclient" (which is the case in our example).

DISSECT dhclient syslog "dhclient"

Configuration options

<module generic>

contains a list of declarations of virtual modules. Virtual modules work exactly like actual modules, except you do not need to load any shared library at start-up time to start them. Instead, virtual modules work by parsing sets of regular expressions.

We describe the standard dhclient virtual module, which is part of the standard configuration file for the generic module, $OCONF/conf.d/12_mod_generic.conf.

That module is meant to parse the syslog messages produced by the dhclient program. That means that you should see

    <vmod dhclient>

This declares a new virtual module with name dhclient. Every virtual module consists of a list of <fieldmatch ⟨regular-expression⟩> … </fieldmatch> declarations. Here are some of them, and we start with the first one. The order is important: the first matching regular expression is the one that is considered to parse the given block of text.

      <fieldmatch "^(bound) to ([0-9.]+) -- renewal in ([0-9]+) seconds\\.">
        str_field action 1 Action
        ipv4_field ip 2 Ip address
        int_field renewal 3 Renewal time
      </fieldmatch>

Here the regular expression matches any message starting with "bound to " followed by an IP address, followed by " -- renewal in " , followed by a number, followed by " seconds." (and possibly other text: if we wanted to match that exactly, we woud add “$" at the end of the regular expression, to match the end of text).

The parenthesized subexpressions, (bound), ([0-9.]+), and ([0-9]+) are recognized as subexpressions 1, 2, and 3 respectively, and converted to types str, ipv4, and int, respectively. The possible field declarations are of the form:

⟨type⟩_field ⟨field name⟩ ⟨field number⟩ ⟨description⟩

The ⟨field name⟩ is any valid Orchids identifier, the ⟨field number⟩ is any non-negative integer, and the ⟨description⟩ consists of the whole remainder of the line. The allowed ⟨type⟩s are the basic types str, bstr, int, uint, ipv4, ipv6, float, ctime, timeval, snmpoid. For each, the generic module will automatically do the required conversion. Hence, the above <fieldmatch> declaration will declare the following Orchids fields:

Field	Type	Description
`.dhclient.action`	`str`	Action
`.dhclient.ip`	`ipv4`	Ip address
`.dhclient.renewal`	`int`	Renewal time

(No, there is no way to specify any monotony in virtual modules yet, sorry.)

You will have noticed that this first regular expression does not match the block of text of our example, "DHCPREQUEST on eth0 to 192.168.30.1 port 67". That is matched by the 5th <fieldmatch> declaration (among 6) in the virtual module:

      <fieldmatch "^(DHCPREQUEST) on ([^ ]+) to ([0-9.]+) port ([0-9]+)$">
        str_field method 1
        str_field interface 2
        ipv4_field dst_ip 3  Destination IP address
        int_field port 4
      </fieldmatch>

That declaration declares the following fields:

Field	Type	Description
`.dhclient.method`	`str`
`.dhclient.interface`	`str`
`.dhclient.dst_ip`	`ipv4`	Destination IP address
`.dhclient.port`	`int`

so that, on our example, we will obtain:

.dhclient.method = "DHCPREQUEST"
.dhclient.interface = "eth0"
.dhclient.dst_ip = 192.168.30.1 (as an ipv4 address)
.dhclient.port = 67

After all those <fieldmatch> declarations, we end with:

</vmod>

to end the declaration of the virtual module. That finishes the declaration of our example virtual module dhclient. There are many others in $OCONF/conf.d/12_mod_generic.conf.

</module>

Fields

Varying. See $OCONF/conf.d/12_mod_generic.conf, and the previous section for examples. The virtual modules are all declared dissectable, in case one would want to further dissect one of the fields they produce.

Obsolescent features

In previous versions of Orchids, one could see all declarations of virtual modules enclosed in <hook> … </hook> declarations, for example:

  <hook syslog "dhclient">

The hook command said that any event produced by the syslog module whose next-to-last field .syslog.prog field is equal to "dhclient" (as in our example) should be parsed by the following virtual module.

This still works, for the time being, but contradicts the principle that all the plumbing of sources and dissectors should be described in the sole file orchids-inputs.conf.