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
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
MQTT Keywords
=============
Various keywords can be used for matching on fields in fixed and variable headers of MQTT messages as well as payload values.
mqtt.protocol_version
---------------------
Match on the value of the MQTT protocol version field in the fixed header.
mqtt.protocol_version uses an :ref:`unsigned 8-bit integer <rules-integer-keywords>`.
The format of the keyword::
mqtt.protocol_version:<min>-<max>;
mqtt.protocol_version:[<|>]<number>;
mqtt.protocol_version:<value>;
Examples:
mqtt.protocol_version:5;
mqtt.type
---------
Match on the MQTT message type (also: control packet type).
Valid values are :
* ``CONNECT``
* ``CONNACK``
* ``PUBLISH``
* ``PUBACK``
* ``PUBREC``
* ``PUBREL``
* ``PUBCOMP``
* ``SUBSCRIBE``
* ``SUBACK``
* ``UNSUBSCRIBE``
* ``UNSUBACK``
* ``PINGREQ``
* ``PINGRESP``
* ``DISCONNECT``
* ``AUTH``
* ``UNASSIGNED``
where ``UNASSIGNED`` refers to message type code 0.
mqtt.type uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
Examples::
mqtt.type:CONNECT;
mqtt.type:PUBLISH;
mqtt.type:2;
mqtt.flags
----------
Match on a combination of MQTT header flags, separated by commas (``,``). Flags may be prefixed by ``!`` to indicate negation, i.e. a flag prefixed by ``!`` must `not` be set to match.
mqtt.flags uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`
Valid flags are:
* ``dup`` (duplicate message)
* ``retain`` (message should be retained on the broker)
Examples::
mqtt.flags:dup,!retain;
mqtt.flags:retain;
mqtt.qos
--------
Match on the Quality of Service request code in the MQTT fixed header.
Valid values are:
* ``0`` (fire and forget)
* ``1`` (at least one delivery)
* ``2`` (exactly one delivery)
Examples::
mqtt.qos:0;
mqtt.qos:2;
mqtt.reason_code
----------------
Match on the numeric value of the reason code that is used in MQTT 5.0 for some message types. Please refer to the specification for the meaning of these values, which are often specific to the message type in question.
mqtt.reason_code uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
Examples::
# match on attempts to unsubscribe from a non-subscribed topic
mqtt.type:UNSUBACK; mqtt.reason_code:17;
# match on publications that were accepted but there were no subscribers
mqtt.type:PUBACK; mqtt.reason_code:16;
# match on connection attempts by banned clients
mqtt.CONNACK; mqtt.reason_code:138;
# match on failed connection attempts due to bad credentials
mqtt.CONNACK; mqtt.reason_code:134;
# match on connections terminated by server shutdowns
mqtt.DISCONNECT; mqtt.reason_code:139;
This keyword is also available under the alias ``mqtt.connack.return_code`` for completeness.
mqtt.connack.session_present
----------------------------
Match on the MQTT CONNACK ``session_present`` flag. Values can be ``yes``, ``true``, ``no`` or ``false``.
Examples::
mqtt.CONNACK; mqtt.connack.session_present:true;
mqtt.connect.clientid
---------------------
Match on the self-assigned client ID in the MQTT CONNECT message.
Examples::
mqtt.connect.clientid; pcre:"/^mosq.*/";
mqtt.connect.clientid; content:"myclient";
``mqtt.connect.clientid`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.connect.flags
------------------
Match on a combination of MQTT CONNECT flags, separated by commas (``,``). Flags may be prefixed by ``!`` to indicate negation, i.e. a flag prefixed by ``!`` must `not` be set to match.
mqtt.connect.flags uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`
Valid flags are:
* ``username`` (message contains a username)
* ``password`` (message contains a password)
* ``will`` (message contains a will definition)
* ``will_retain`` (will should be retained on broker)
* ``clean_session`` (start with a clean session)
Examples::
mqtt.connect.flags:username,password,!will;
mqtt.connect.flags:username,!password;
mqtt.connect.flags:clean_session;
mqtt.connect.password
---------------------
Match on the password credential in the MQTT CONNECT message.
Examples::
mqtt.connect.password; pcre:"/^123[0-9]*/";
mqtt.connect.password; content:"swordfish";
``mqtt.connect.password`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.connect.protocol_string
----------------------------
Match on the protocol string in the MQTT CONNECT message. In contrast to ``mqtt.protocol_version`` this is a property that is only really relevant in the initial CONNECT communication and never used again; hence it is organized under ``mqtt.connect``.
Examples::
mqtt.connect.protocol_string; content:"MQTT";
mqtt.connect.protocol_string; content:"MQIsdp";
``mqtt.connect.protocol_string`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.connect.username
---------------------
Match on the username credential in the MQTT CONNECT message.
Examples::
mqtt.connect.username; content:"benson";
``mqtt.connect.username`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.connect.willmessage
------------------------
Match on the will message in the MQTT CONNECT message, if a will is defined.
Examples::
mqtt.connect.willmessage; pcre:"/^fooba[rz]/";
mqtt.connect.willmessage; content:"hunter2";
``mqtt.connect.willmessage`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.connect.willtopic
----------------------
Match on the will topic in the MQTT CONNECT message, if a will is defined.
Examples::
mqtt.connect.willtopic; pcre:"/^hunter[0-9]/";
``mqtt.connect.willtopic`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.publish.message
--------------------
Match on the payload to be published in the MQTT PUBLISH message.
Examples::
mqtt.type:PUBLISH; mqtt.publish.message; pcre:"/uid=[0-9]+/";
# match on published JPEG images
mqtt.type:PUBLISH; mqtt.publish.message; content:"|FF D8 FF E0|"; startswith;
``mqtt.publish.message`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.publish.topic
------------------
Match on the topic to be published to in the MQTT PUBLISH message.
Examples::
mqtt.publish.topic; content:"mytopic";
``mqtt.publish.topic`` is a 'sticky buffer' and can be used as ``fast_pattern``.
mqtt.subscribe.topic
--------------------
Match on any of the topics subscribed to in a MQTT SUBSCRIBE message.
Examples::
mqtt.subscribe.topic; content:"mytopic";
``mqtt.subscribe.topic`` is a 'sticky buffer' and can be used as ``fast_pattern``.
``mqtt.subscribe.topic`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
mqtt.unsubscribe.topic
----------------------
Match on any of the topics unsubscribed from in a MQTT UNSUBSCRIBE message.
Examples::
mqtt.unsubscribe.topic; content:"mytopic";
``mqtt.unsubscribe.topic`` is a 'sticky buffer' and can be used as ``fast_pattern``.
``mqtt.unsubscribe.topic`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
Additional information
----------------------
More information on the protocol can be found here:
* MQTT 3.1: `<https://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html>`_
* MQTT 3.1.1: `<https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html>`_
* MQTT 5.0: `<https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html>`_
|
