1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
.. index:: ! mmdarwin
.. role:: json(code)
:language: json
***************************
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
^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "none"
The key name to use to store the returned data.
For example, given the following log line:
.. code-block:: json
{
"from": "192.168.1.42",
"date": "2012-12-21 00:00:00",
"status": "200",
"data": {
"status": true,
"message": "Request processed correctly"
}
}
and the :json:`"certitude"` key, the enriched log line would be:
.. code-block:: json
:emphasize-lines: 9
{
"from": "192.168.1.42",
"date": "2012-12-21 00:00:00",
"status": "200",
"data": {
"status": true,
"message": "Request processed correctly"
},
"certitude": 0
}
where :json:`"certitude"` represents the score returned by Darwin.
socketpath
^^^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "none"
The Darwin filter socket path to use.
response
^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", \"no", "no", "none"
Tells the Darwin filter what to do next:
* :json:`"no"`: no response will be sent, nothing will be sent to next filter.
* :json:`"back"`: a score for the input will be returned by the filter, nothing will be forwarded to the next filter.
* :json:`"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.
* :json:`"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 :json:`"darwin"` or :json:`"both"`, if a next filter if configured but you ask for a :json:`"back"` response, the next filter **WILL NOT** receive anything!
filtercode
^^^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "0x00000000", "no", "none"
Each Darwin module has a unique filter code. For example, the code of the hostlookup filter is :json:`"0x66726570"`.
This code was mandatory but has now become obsolete. you can leave it as it is.
fields
^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"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 (:json:`"!"`), 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:
.. code-block:: json
{
"from": "192.168.1.42",
"date": "2012-12-21 00:00:00",
"status": "200",
"data": {
"status": true,
"message": "Request processed correctly"
}
}
and the :json:`"fields"` array:
.. code-block:: none
["!from", "!data!status", "rsyslog"]
The parameters sent to Darwin would be :json:`"192.168.1.42"`, :json:`true` and :json:`"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.
.. _`Darwin documentation`: https://github.com/VultureProject/darwin/wiki
send_partial
^^^^^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"boolean", "off", "no", "none"
Whether to send to Darwin if not all :json:`"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:
.. code-block:: json
{
"from": "192.168.1.42",
"date": "2012-12-21 00:00:00",
"status": "200",
"data": {
"status": true,
"message": "Request processed correctly"
}
}
and the :json:`"fields"` array:
.. code-block:: none
["!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.
.. code-block:: none
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")
}
|
