policy/protocols/mqtt/main.zeek

MQTT

Implements base functionality for MQTT (v3.1.1) analysis. Generates the mqtt.log file.

Namespace:MQTT
Imports:base/protocols/mqtt/consts.zeek

Summary

Types

MQTT::ConnectInfo: record  
MQTT::PublishInfo: record  
MQTT::State: record Data structure to track pub/sub messaging state of a given connection.
MQTT::SubUnsub: enum &redef  
MQTT::SubscribeInfo: record  

Events

MQTT::log_mqtt: event Event that can be handled to access the MQTT record as it is sent on to the logging framework.

Functions

MQTT::publish_expire: function The expiration function for published messages that haven’t been logged yet simply causes the message to be logged.
MQTT::subscribe_expire: function The expiration function for subscription messages that haven’t been logged yet simply causes the message to be logged.

Detailed Interface

Types

MQTT::ConnectInfo
Type:

record

ts: time &log

Timestamp for when the event happened

uid: string &log

Unique ID for the connection

id: conn_id &log

The connection’s 4-tuple of endpoint addresses/ports

proto_name: string &log &optional

Indicates the protocol name

proto_version: string &log &optional

The version of the protocol in use

client_id: string &log &optional

Unique identifier for the client

connect_status: string &log &optional

Status message from the server in response to the connect request

will_topic: string &log &optional

Topic to publish a “last will and testament” message to

will_payload: string &log &optional

Payload to publish as a “last will and testament”

MQTT::PublishInfo
Type:

record

ts: time &log

Timestamp for when the publish message started

uid: string &log

UID for the connection

id: conn_id &log

ID fields for the connection

from_client: bool &log

Indicates if the message was published by the client of this connection or published to the client.

retain: bool &log

Indicates if the message was to be retained by the server

qos: string &log

QoS level set for the message

status: string &log &default = "incomplete_qos" &optional

Status of the published message. This will be set to “incomplete_qos” if the full back and forth for the requested level of QoS was not seen. Otherwise if it’s successful the field will be “ok”.

topic: string &log

Topic the message was published to

payload: string &log

Payload of the message

payload_len: count &log

The actual length of the payload in the case the payload field’s contents were truncated according to MQTT::max_payload_size.

ack: bool &default = F &optional

Track if the message was acked

rec: bool &default = F &optional

Indicates if the server sent the RECEIVED qos message

rel: bool &default = F &optional

Indicates if the client sent the RELEASE qos message

comp: bool &default = F &optional

Indicates if the server sent the COMPLETE qos message

qos_level: count &default = 0 &optional

Internally used for comparing numeric qos level

MQTT::State
Type:

record

publish: table [count] of MQTT::PublishInfo &optional &write_expire = 5.0 secs &expire_func = MQTT::publish_expire

Published messages that haven’t been logged yet.

subscribe: table [count] of MQTT::SubscribeInfo &optional &write_expire = 5.0 secs &expire_func = MQTT::subscribe_expire

Subscription/unsubscription messages that haven’t been ACK’d or logged yet.

Data structure to track pub/sub messaging state of a given connection.

MQTT::SubUnsub
Type:

enum

MQTT::SUBSCRIBE
MQTT::UNSUBSCRIBE
Attributes:

&redef

MQTT::SubscribeInfo
Type:

record

ts: time &log

Timestamp for when the subscribe or unsubscribe request started

uid: string &log

UID for the connection

id: conn_id &log

ID fields for the connection

action: MQTT::SubUnsub &log

Indicates if a subscribe or unsubscribe action is taking place

topics: string_vec &log

The topics (or topic patterns) being subscribed to

qos_levels: index_vec &log &optional

QoS levels requested for messages from subscribed topics

granted_qos_level: count &log &optional

QoS level the server granted

ack: bool &log &default = F &optional

Indicates if the request was acked by the server

Events

MQTT::log_mqtt
Type:event (rec: MQTT::ConnectInfo)

Event that can be handled to access the MQTT record as it is sent on to the logging framework.

Functions

MQTT::publish_expire
Type:function (tbl: table [count] of MQTT::PublishInfo, idx: count) : interval

The expiration function for published messages that haven’t been logged yet simply causes the message to be logged.

MQTT::subscribe_expire
Type:function (tbl: table [count] of MQTT::SubscribeInfo, idx: count) : interval

The expiration function for subscription messages that haven’t been logged yet simply causes the message to be logged.