Darwin connector (mmdarwin)

Module Name: mmdarwin
Author: Guillaume Catto <guillaume.catto@advens.fr>

Purpose

Darwin is an open source Artificial Intelligence Framework for CyberSecurity. The mmdarwin module allows us to call Darwin in order to enrich our JSON-parsed logs with a decision stored in a specific key.

How to build the module

To compile Rsyslog with mmdarwin you’ll need to:

  • set –enable-mmdarwin on configure

Configuration Parameter

Input Parameters

key

type default mandatory obsolete legacy directive
word none yes none

The key name used to enrich our logs.

For example, given the following log line:

{
    "from": "192.168.1.42",
    "date": "2012-12-21 00:00:00",
    "status": "200",
    "data": {
        "status": true,
        "message": "Request processed correctly"
    }
}

and the “certitude” key, the enriched log line would be:

{
    "from": "192.168.1.42",
    "date": "2012-12-21 00:00:00",
    "status": "200",
    "data": {
        "status": true,
        "message": "Request processed correctly"
    },
    "certitude": 0
}

where “certitude” represents the score returned by Darwin.

socketpath

type default mandatory obsolete legacy directive
word none yes none

The Darwin filter socket path to call.

response

type default mandatory obsolete legacy directive
word none yes none

Tell the Darwin filter what to do with its decision:

  • “no”: no response will be sent
  • “back”: Darwin will send its decision to the caller
  • “darwin”: Darwin will send its decision to the next filter
  • “both”: Darwin will send its decision to both the caller and the next filter

filtercode

type default mandatory obsolete legacy directive
word none yes none

Each Darwin module has a unique filter code. For example, the code of the injection filter is “0x696E6A65”. You need to provide a code corresponding to the filter you want to use.

fields

type default mandatory obsolete legacy directive
array none yes none

Array containing values to be sent to Darwin as parameters.

Two types of values can be set:

  • if it starts with a bang (“!”), mmdarwin will search in the JSON-parsed log line the associated value. You can search in subkeys as well: just add a bang to go to a deeper level.
  • otherwise, the value is considered static, and will be forwarded directly to Darwin.

For example, given the following log line:

{
    "from": "192.168.1.42",
    "date": "2012-12-21 00:00:00",
    "status": "200",
    "data": {
        "status": true,
        "message": "Request processed correctly"
    }
}

and the “fields” array:

["!from", "!data!status", "rsyslog"]

The parameters sent to Darwin would be “192.168.1.42”, true and “rsyslog”.

Note that the order of the parameters is important. Thus, you have to be careful when providing the fields in the array.

Configuration example

This example shows a possible configuration of mmdarwin.

module(load="imtcp")
module(load="mmjsonparse")
module(load="mmdarwin")

input(type="imtcp" port="8042" Ruleset="darwinruleset")

ruleset(name="darwinruleset") {
   action(type="mmjsonparse" cookie="")
   action(type="mmdarwin" socketpath="/path/to/reputation_1.sock" fields=["!srcip", "ATTACK;TOR"] key="reputation" response="back" filtercode="0x72657075")

   call darwinoutput
}

ruleset(name="darwinoutput") {
    action(type="omfile" file="/path/to/darwin_output.log")
}

See also

Help with configuring/using Rsyslog:

  • Mailing list - best route for general questions
  • GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with Rsyslog
  • Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to Rsyslog: