doc/userguide/rules/mqtt-keywords.rst
Various keywords can be used for matching on fields in fixed and variable headers of MQTT messages as well as payload values.
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;
Match on the MQTT message type (also: control packet type). Valid values are :
CONNECTCONNACKPUBLISHPUBACKPUBRECPUBRELPUBCOMPSUBSCRIBESUBACKUNSUBSCRIBEUNSUBACKPINGREQPINGRESPDISCONNECTAUTHUNASSIGNEDwhere UNASSIGNED refers to message type code 0.
mqtt.type uses an :ref:unsigned 8-bits integer <rules-integer-keywords>.
mqtt.type is also a :ref:multi-integer <multi-integers>.
Examples::
mqtt.type:CONNECT; mqtt.type:PUBLISH; mqtt.type:2;
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> with bitmasks.
Valid flags are:
dup (duplicate message)retain (message should be retained on the broker)Examples::
mqtt.flags:dup,!retain; mqtt.flags:retain;
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;
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::
mqtt.type:UNSUBACK; mqtt.reason_code:17;
mqtt.type:PUBACK; mqtt.reason_code:16;
mqtt.CONNACK; mqtt.reason_code:138;
mqtt.CONNACK; mqtt.reason_code:134;
mqtt.DISCONNECT; mqtt.reason_code:139;
This keyword is also available under the alias mqtt.connack.return_code for completeness.
Match on the MQTT CONNACK session_present flag. Values can be yes, true, no or false.
Examples::
mqtt.CONNACK; mqtt.connack.session_present:true;
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.
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> with bitmasks.
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;
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.
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.
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.
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.
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.
Match on the payload to be published in the MQTT PUBLISH message.
Examples::
mqtt.type:PUBLISH; mqtt.publish.message; pcre:"/uid=[0-9]+/";
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.
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.
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.
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.
More information on the protocol can be found here:
<https://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html>_<https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html>_<https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html>_