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

Redefinable Options

MQTT::ports: set &redef

Well-known ports for MQTT.

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`

Redefinitions

`Log::ID`: `enum`	`MQTT::CONNECT_LOG` `MQTT::PUBLISH_LOG` `MQTT::SUBSCRIBE_LOG`
`connection`: `record`	New Fields: `connection` mqtt: `MQTT::ConnectInfo` `&optional` mqtt_state: `MQTT::State` `&optional`

Events

MQTT::log_mqtt: event

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

Hooks

`MQTT::log_policy_connect`: `Log::PolicyHook`
`MQTT::log_policy_publish`: `Log::PolicyHook`
`MQTT::log_policy_subscribe`: `Log::PolicyHook`

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

Redefinable Options

MQTT::ports 

Type:

set [port]

Attributes:

&redef

Default:

{
   1883/tcp
}

Well-known ports for MQTT.

Types

MQTT::ConnectInfo 

Type:

record

Fields:

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

Fields:

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

Fields:

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

Fields:

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.

Hooks

MQTT::log_policy_connect 

Type:: Log::PolicyHook

MQTT::log_policy_publish 

Type:: Log::PolicyHook

MQTT::log_policy_subscribe 

Type:: Log::PolicyHook

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.