Skip to content

Darwin configuration

Jump to bottom
frikilax edited this page May 18, 2020 · 8 revisions

Description

The configuration file for Darwin must be a valid JSON structure. There are 2 supported formats for the configuration: "legacy" and "v2".

Configuration files are validated and should respect formats described below.

"v2" configuration format

This format resembles legacy, but the json filters are objects contained in a list without variable keys.

Parameters

This file format should contain "version" and "filters" keys at the root, and may contain "report_stats".

mandatory parameters are prepended with a "*", field type and defaults (if present) are described in [].

  • *version [number]: should be 2, allows to check the validator that this is indeed a v2 conf format
  • *filters [list]: a list containing all the filters you want to run, in the form:
    • *name [string]: the friendly name of the filter, can be whatever you want but cannot contain spaces and should be more than 1 character
    • *exec_path [string]: the path to the filter
    • *config_file [string]: the path for the filter's configuration
    • next_filter [string]: the next_filter called after this one, if the filter is called in both or darwin mode
    • nb_thread [number, 5]: the number of thread spawned by the filter (between 1 and 100)
    • output [string, "NONE"]: which body the filter will send to the next filter. You can have :
      • RAW: body received by the filter
      • PARSED: body received by the filter after been parsed
      • LOG: filter's result under log form (json)
      • NONE: no body send
    • log_level [string, "WARNING"]: which level of log you want to have. You can have :
      • DEBUG
      • INFO
      • WARNING
      • CRITICAL
      • ERROR
    • cache_size [number, 0]: Integer specifying the in-memory number of cache entries, but this might not be used by the filter (check filters' documentation for details)
    • threshold [number, 100]: Integer specifying the minimum certitude at which the filter will output an alert, 100 being the (inclusive) maximum.
  • report_stats [object]: ways to report at regular intervals statistics about the filters
    • redis [object]: report stats on Redis:
      • unix_path [string]: the fullpath to the Redis unix socket
      • ip [string]: the IP of the Redis server
      • port [number, depends on ip]: the port of the server
      • *channel [string, mandatory if no list]: the channel on which to publish
      • *list [string, mandatory if no channel]: the list on which to append
    • file [object]: report stats on a file:
      • filepath [string]: the fullpath to the file
      • permissions [number, 640]: the permissions to set if the file is created
    • interval [number, 60]: the number of seconds between two reports (must obviously be over 0)

Example

This is an example v2 configuration:

{
  "version": 2,
  "filters": [
    {
      "name": "session_1",
      "exec_path": "/home/darwin/filters/darwin_session",
      "config_file": "/home/darwin/conf/fsession/fsession.conf",
      "next_filter": "logs_1",
      "output": "LOG",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    },
    {
      "name": "user_agent_1",
      "exec_path": "/home/darwin/filters/darwin_user_agent",
      "config_file": "/home/darwin/conf/fuseragent/fuseragent.conf",
      "next_filter": "logs_1",
      "output": "LOG",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    },
    {
      "name": "dga_1",
      "exec_path": "/home/darwin/filters/darwin_dga",
      "config_file": "/home/darwin/conf/fdga/fdga.conf",
      "next_filter": "logs_1",
      "output": "LOG",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG",
      "threshold": 95
    },
    {
      "name": "anomaly_1",
      "exec_path": "/home/darwin/filters/darwin_anomaly",
      "config_file": "/home/darwin/conf/fanomaly/fanomaly.conf",
      "next_filter": "logs_1",
      "output": "LOG",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    },
    {
      "name": "logs_1",
      "exec_path": "/home/darwin/filters/darwin_logs",
      "config_file": "/home/darwin/conf/flogs/flogs.conf",
      "next_filter": "end_1",
      "output": "NONE",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    },
    {
      "name": "end_1",
      "exec_path": "/home/darwin/filters/darwin_end",
      "config_file": "/home/darwin/conf/fsession/fend.conf",
      "next_filter": "",
      "output": "NONE",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    },
    {
      "name": "ftanomaly_1",
      "exec_path": "/home/darwin/filters/darwin_tanomaly",
      "config_file": "/home/darwin/conf/ftanomaly/ftanomaly.conf",
      "next_filter": "",
      "output": "NONE",
      "cache_size": 0,
      "nb_thread": 5,
      "log_level": "DEBUG"
    }
  ],
  "report_stats": {
      "redis": {
          "ip": "127.0.0.1",
          "port": 6379,
          "channel": "darwin.stats"
      },
      "file": {
          "filepath": "/tmp/darwin-stats",
          "permissions": 640
      },
      "interval": 5
  }
}

"Legacy" Configuration format

This type of format was the first format to be implemented in Darwin. It is described here and still supported, but v2 should be preferred over this one (especially if some capabilities such as stats reporting are required by the user).

Parameters

This file format should be a list of named objects, with the key being the name of the filter.

mandatory parameters are prepended with a "*", field type and defaults (if present) are described in [].

  • *exec_path [string]: the path to the filter
  • *config_file [string]: the path for the filter's configuration
  • next_filter [string]: the next_filter called after this one, if the filter is called in both or darwin mode
  • nb_thread [number/valid-number-string, 5]: the number of thread spawned by the filter (between 1 and 100)
  • output [string, "NONE"]: which body the filter will send to the next filter. You can have :
    • RAW: body received by the filter
    • PARSED: body received by the filter after been parsed
    • LOG: filter's result under log form (json)
    • NONE: no body send
  • log_level [string, "WARNING"]: which level of log you want to have. You can have :
    • DEBUG
    • INFO
    • WARNING
    • CRITICAL
    • ERROR
  • cache_size [number/valid-number-string, 0]: Integer specifying the in-memory number of cache entries, but this might not be used by the filter (check filters' documentation for details)
  • threshold [number, 100]: Integer specifying the minimum certitude at which the filter will output an alert, 100 being the (inclusive) maximum.

Example

This is an example legacy configuration:

{
  "session_1": {
    "exec_path": "/home/darwin/filters/darwin_session",
    "config_file": "/home/darwin/conf/fsession/fsession.conf",
    "next_filter": "logs_1",
    "output": "LOG",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG"
  },
  "user_agent_1": {
    "exec_path": "/home/darwin/filters/darwin_user_agent",
    "config_file": "/home/darwin/conf/fuseragent/fuseragent.conf",
    "next_filter": "logs_1",
    "output": "LOG",
    "cache_size": "0",
    "nb_thread": "5",
    "log_level": "DEBUG"
  },
  "dga_1": {
    "exec_path": "/home/darwin/filters/darwin_dga",
    "config_file": "/home/darwin/conf/fdga/fdga.conf",
    "next_filter": "logs_1",
    "output": "LOG",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG",
    "threshold": 95
  },
  "anomaly_1": {
    "exec_path": "/home/darwin/filters/darwin_anomaly",
    "config_file": "/home/darwin/conf/fanomaly/fanomaly.conf",
    "next_filter": "logs_1",
    "output": "LOG",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG"
  },
  "logs_1": {
    "exec_path": "/home/darwin/filters/darwin_logs",
    "config_file": "/home/darwin/conf/flogs/flogs.conf",
    "next_filter": "end_1",
    "output": "NONE",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG"
  },
  "end_1": {
    "exec_path": "/home/darwin/filters/darwin_end",
    "config_file": "/home/darwin/conf/fend/fend.conf",
    "next_filter": "",
    "output": "NONE",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG"
  },
  "ftanomaly_1": {
    "exec_path": "/home/darwin/filters/darwin_tanomaly",
    "config_file": "/home/darwin/conf/ftanomaly/ftanomaly.conf",
    "next_filter": "",
    "output": "NONE",
    "cache_size": 0,
    "nb_thread": 5,
    "log_level": "DEBUG"
  }
}
Clone this wiki locally