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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
Multi Tenancy
=============
Introduction
------------
Multi tenancy support allows different tenants to use different
rule sets with different rule variables.
Tenants are identified by their `selector`; a `selector` can be
a VLAN, interface/device, or from a pcap file ("direct").
YAML
----
Add a new section in the main ("master") Suricata configuration file -- ``suricata.yaml`` -- named ``multi-detect``.
Settings:
* `enabled`: yes/no -> is multi-tenancy support enabled
* `selector`: direct (for unix socket pcap processing, see below), VLAN or device
* `loaders`: number of `loader` threads, for parallel tenant loading at startup
* `tenants`: list of tenants
* `config-path`: path from where the tenant yamls are loaded
* id: tenant id (numeric values only)
* yaml: separate yaml file with the tenant specific settings
* `mappings`:
* VLAN id or device: The outermost VLAN is used to match.
* tenant id: tenant to associate with the VLAN id or device
::
multi-detect:
enabled: yes
#selector: direct # direct or vlan
selector: vlan
loaders: 3
tenants:
- id: 1
yaml: tenant-1.yaml
- id: 2
yaml: tenant-2.yaml
- id: 3
yaml: tenant-3.yaml
mappings:
- vlan-id: 1000
tenant-id: 1
- vlan-id: 2000
tenant-id: 2
- vlan-id: 1112
tenant-id: 3
The tenant-1.yaml, tenant-2.yaml, tenant-3.yaml each contain a partial
configuration:
::
# Set the default rule path here to search for the files.
# if not set, it will look at the current working dir
default-rule-path: /etc/suricata/rules
rule-files:
- rules1
# You can specify a threshold config file by setting "threshold-file"
# to the path of the threshold config file:
# threshold-file: /etc/suricata/threshold.config
classification-file: /etc/suricata/classification.config
reference-config-file: /etc/suricata/reference.config
# Holds variables that would be used by the engine.
vars:
# Holds the address group vars that would be passed in a Signature.
# These would be retrieved during the Signature address parsing stage.
address-groups:
HOME_NET: "[192.168.0.0/16,10.0.0.0/8,172.16.0.0/12]"
EXTERNAL_NET: "!$HOME_NET"
...
port-groups:
HTTP_PORTS: "80"
SHELLCODE_PORTS: "!80"
...
vlan-id
~~~~~~~
Assign tenants to VLAN ids. Suricata matches the outermost VLAN id with this value.
Multiple VLANs can have the same tenant id. VLAN id values must be between 1 and 4094.
Example of VLAN mapping::
mappings:
- vlan-id: 1000
tenant-id: 1
- vlan-id: 2000
tenant-id: 2
- vlan-id: 1112
tenant-id: 3
The mappings can also be modified over the unix socket, see below.
Note: can only be used if ``vlan.use-for-tracking`` is enabled.
device
~~~~~~
Assign tenants to devices. A single tenant can be assigned to a device.
Multiple devices can have the same tenant id.
Example of device mapping::
mappings:
- device: ens5f0
tenant-id: 1
- device: ens5f1
tenant-id: 3
The mappings are static and cannot be modified over the unix socket.
Note: Not currently supported for IPS.
Note: support depends on a capture method using the 'livedev' API. Currently
these are: pcap, AF_PACKET, PF_RING and Netmap.
Per tenant settings
-------------------
The following settings are per tenant:
* default-rule-path
* rule-files
* classification-file
* reference-config-file
* threshold-file
* address-vars
* port-vars
Unix Socket
-----------
Registration
~~~~~~~~~~~~
``register-tenant <id> <yaml>``
Examples:
::
register-tenant 1 tenant-1.yaml
register-tenant 2 tenant-2.yaml
register-tenant 3 tenant-3.yaml
register-tenant 5 tenant-5.yaml
register-tenant 7 tenant-7.yaml
``unregister-tenant <id>``
::
unregister-tenant 2
unregister-tenant 1
Unix socket runmode (pcap processing)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Unix Socket ``pcap-file`` command is used to associate the tenant with
the pcap:
::
pcap-file traffic1.pcap /logs1/ 1
pcap-file traffic2.pcap /logs2/ 2
pcap-file traffic3.pcap /logs3/ 3
pcap-file traffic4.pcap /logs5/ 5
pcap-file traffic5.pcap /logs7/ 7
This runs the traffic1.pcap against tenant 1 and it logs into /logs1/,
traffic2.pcap against tenant 2 and logs to /logs2/ and so on.
Live traffic mode
~~~~~~~~~~~~~~~~~
Multi-tenancy supports both VLAN and devices with live traffic.
In the master configuration yaml file, specify ``device`` or ``vlan`` for the ``selector`` setting.
Registration
~~~~~~~~~~~~
Tenants can be mapped to vlan ids.
``register-tenant-handler <tenant id> vlan <vlan id>``
::
register-tenant-handler 1 vlan 1000
``unregister-tenant-handler <tenant id> vlan <vlan id>``
::
unregister-tenant-handler 4 vlan 1111
unregister-tenant-handler 1 vlan 1000
The registration of tenant and tenant handlers can be done on a
running engine.
Reloads
~~~~~~~
Reloading all tenants:
``reload-tenants``
::
reload-tenants
Reloading a single tenant:
``reload-tenant <tenant id> [yaml path]``
::
reload-tenant 1 tenant-1.yaml
reload-tenant 5
The ``[yaml path]`` is optional. If it isn't provided, the original path of
the tenant will be used during the reload.
Eve JSON output
---------------
When multi-tenant support is configured and the detect engine is active then
all EVE-types that report based on flows will also report the corresponding
``tenant_id`` for events matching a tenant configuration.
|
