Management socket

A UNIX socket is available for runtime administration /var/run/darwin/socket/darwin.sock. For now, it allows the following commands:

Monitoring

Can be used at any time to get monitoring information from all the currently working filters.

Request:

{
  "type": "monitor"
}

Response example:

{
  "logs_1": {
    "status": "running",
    "connections": 0,
    "received": 0,
    "entryErrors": 0,
    "matches": 0,
    "failures": 0,
    "proc_stats": {
      "memory_percent": 0.24425256572322326,
      "cpu_percent": 0.0
    }
  },
  "session_1": {"status": "error"},
  "content_inspection_1": {"status": "error"}
}

Here logs_1 works correctly, but session_1 and content_inspection_1 are not running.

Valid values for status are starting, configuring, running and stopping.

When a filter runs normally, the monitor shall return its statistics, the proc_stats fields can be customized to query specific/additional fields during the call.

Example request with custom proc_stats:

{
  "type": "monitor",
  "proc_stats": ["username", "pid", "ppid"]
}

And the answer:

{
  "logs_1": {
    "status": "running",
    "connections": 0,
    "received": 0,
    "entryErrors": 0,
    "matches": 0,
    "failures": 0,
    "proc_stats": {
      "pid": 5593,
      "username": "root",
      "ppid": 1
    }
  },
  "session_1": {"status": "error"},
  "content_inspection_1": {"status": "error"}}

Filters Update

SHOULD be used to reload configuration of some filters; to do so, please rewrite the configuration file first.

Also updates the configuration of the stats reporter.

Request:

{
  "type": "update_filters",
  "filters": [
    "hostlookup_1",
    "logs_1"
  ]
}

Response (only sent when update is finished, it may take a few moments):

Success:

{
  "status": "OK"
}

Failure:

{
  "status": "KO",
  "errors": [
    {"filter": "logs_1", "error": "PID file not accessible"}
  ]
}

Diff update

The command can also be used without specifying the filters key (or leaving it empty). In that case, the manager will analyse the difference between its currently launched filters' names and the ones in the loaded configuration file. Every new filter name will be considered new and started, and every name disappearing will be considered old and the corresponding filter will be stopped.

WARNING: as such, this option will only detect new and deleted entries based on their NAME -> if a filter's option is simply modified without changing its name, the user should still call the command while specifying the filter name to ensure proper reloading!

For example, with an initial 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"
    }
  ],
  "report_stats": {
      "file": {
          "filepath": "/tmp/darwin-stats",
          "permissions": 640
      },
      "interval": 5
  }
}

After starting the manager, if the configuration is changed to:

{
  "version": 2,
  "filters": [
    {
      "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": "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": "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": "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": {
      "file": {
          "filepath": "/tmp/darwin-stats",
          "permissions": 640
      },
      "interval": 5
  }
}

After sending {"type": "update_filters"} or {"type": "update_filters", "filters": []}

• the filter user_agent_1 will be stopped
• the filters dga_1, logs_1, ftanomaly_1 will be started
• the filter session_1 will stay as it is