# Darwin connector (mmdarwin)

Module Name: | mmdarwin
Author: | Guillaume Catto <guillaume.catto@advens.fr>, Theo Bertin <theo.bertin@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 score, and/or to allow Darwin to generate alerts.

## 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 to use to store the returned data.

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

#### response

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | "no” | no | none

Tells the Darwin filter what to do next:

- `"no"`: no response will be sent, nothing will be sent to next filter.

- `"back"`: a score for the input will be returned by the filter, nothing will be forwarded to the next filter.

- `"darwin"`: the data provided will be forwarded to the next filter (in the format specified in the filter’s configuration), no response will be given to mmdarwin.

- `"both"`: the filter will respond to mmdarwin with the input’s score AND forward the data (in the format specified in the filter’s configuration) to the next filter.

Note

Please be mindful when setting this parameter, as the called filter will only forward data to the next configured filter if you ask the filter to do so with `"darwin"` or `"both"`, if a next filter if configured but you ask for a `"back"` response, the next filter WILL NOT receive anything!

#### filtercode

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | 0x00000000 | no | none

Each Darwin module has a unique filter code. For example, the code of the hostlookup filter is `"0x66726570"`. This code was mandatory but has now become obsolete. you can leave it as it is.

#### 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

The order of the parameters is important. Thus, you have to be careful when providing the fields in the array. Refer to Darwin documentation to see what each filter requires as parameters.

#### send_partial

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
boolean | off | no | none

Whether to send to Darwin if not all `"fields"` could be found in the message, or not. All current Darwin filters required a strict number (and format) of parameters as input, so they will most likely not process the data if some fields are missing. This should be kept to “off”, unless you know what you’re doing.

For example, for 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", "!this!field!is!not!in!message"]

the third field won’t be found, so the call to Darwin will be dropped.

## 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="darwin_ruleset")

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

       call darwin_output
    }

    ruleset(name="darwin_output") {
        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`

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

Copyright 2008-2023 Rainer Gerhards (Großrinderfeld), and Others.