Protocol 73 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
mqttMessage Queuing Telemetry Transport (IoT & IIoT)

IoT Sensor Publishes & Wildcard # Subscriptions (sensor <-> broker mqtt)

Default Port / Protocol
TCP 1883
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
mqtt
Standards & Specs
OASIS MQTT v3.1.1, OASIS MQTT v5.0
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP 1883MQTT

What It Does on the Wire

Test whether a compromised smart thermostat can subscribe to "factory/#" on TCP 1883 — mqtt computes the variable-byte Remaining Length encoding automatically.

Message Queuing Telemetry Transport (mqtt, OASIS MQTT v3.1.1) connects IoT sensors, smart-grid meters, and Industrial IoT (Sparkplug B / IIoT) gateways to brokers (Mosquitto, EMQX, HiveMQ, AWS IoT) over TCP port 1883 (or 8883 over TLS).

FrameAssembly encodes the MQTT Fixed Header (4-bit Control Packet Type + QoS/Retain flags + variable-byte Remaining Length) and Variable Header for connect, connack, publish, puback, subscribe, suback, pingreq, pingresp, and disconnect.

Test OT / IIoT Topic-Level Deep Packet Inspection Firewalls

Verify industrial firewalls allow mqtt publish topic "line1/sensors/temp" while blocking wildcard subscribe topic "#" enumeration or unauthorized actuator command topics.

Detect Exposed Anonymous MQTT Brokers (returncode 0)

Simulate unauthenticated connect -> connack returncode 0 handshakes on TCP 1883 to test IoT security posture rules.

QoS 1 (publish + puback) & Retain Flag Broker Testing

Validate message delivery acknowledgments (qos 1 pktid 10) and retained state (retain) in telemetry pipelines.

Minimal Quickstart (mqtt_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

mqtt_quickstart.frasm11 lines
Open in Playground
host edge_gw { ip 10.60.10.25 }
host broker { ip 10.60.10.10 }
compile {
edge_gw -> broker tcp syn srcport 51883 dstport 1883 wait 1ms
edge_gw <- broker tcp syn ack wait 1ms
edge_gw -> broker tcp ack wait 1ms
edge_gw -> broker mqtt connect clientid "gw-rack04" keepalive 60 wait 2ms
edge_gw <- broker mqtt connack returncode 0 wait 2ms
edge_gw -> broker mqtt publish topic "dc1/rack04/kw" qos 0 retain payload "4.85"
}

What the Compiler Calculates So You Don't Have To

  • Defaults to TCP destination port 1883 (psh ack) and encodes the multi-byte variable-length Remaining Length field per OASIS MQTT §2.2.3.
  • Encodes the "MQTT" Protocol Level 4 header inside connect, and includes the 2-byte Packet Identifier (pktid) automatically on qos 1 / qos 2 publish, puback, subscribe, and suback packets.
  • Appends payload "<text>" directly as the UTF-8 topic message payload on publish frames.
Multi-Frame Lab · Ready to Compile

IIoT Gateway Connect, Wildcard Topic Subscribe, QoS 1 Publish & Keepalive Ping

Connects an industrial gateway to TCP 1883, subscribes to control commands, publishes a qos 1 retained sensor reading acknowledged via puback, and exchanges pingreq/pingresp.

mqtt_iiot_telemetry.frasm20 lines
Open in Playground
host plc_gw { ip 192.168.80.21 }
host mqtt_broker { ip 192.168.80.10 }
compile {
plc_gw -> mqtt_broker tcp syn srcport 52883 dstport 1883 win 65535 mss 1460 wait 1ms
plc_gw <- mqtt_broker tcp syn ack win 65535 mss 1460 wait 1ms
plc_gw -> mqtt_broker tcp ack wait 1ms
plc_gw -> mqtt_broker mqtt connect clientid "line2-plc-gw" keepalive 30 wait 2ms
plc_gw <- mqtt_broker mqtt connack returncode 0 wait 2ms
// 1. Subscribe to actuator commands (pktid 1)
plc_gw -> mqtt_broker mqtt subscribe pktid 1 topic "plant1/line2/cmd" qos 1 wait 2ms
plc_gw <- mqtt_broker mqtt suback pktid 1 wait 3ms
// 2. Publish QoS 1 retained telemetry (pktid 2 -> puback)
plc_gw -> mqtt_broker mqtt publish topic "plant1/line2/pressure_bar" qos 1 retain pktid 2 payload "{\"bar\":6.42}" wait 2ms
plc_gw <- mqtt_broker mqtt puback pktid 2 wait 10ms
// 3. Keepalive heartbeat + clean disconnect
plc_gw -> mqtt_broker mqtt pingreq wait 1ms
plc_gw <- mqtt_broker mqtt pingresp wait 2ms
plc_gw -> mqtt_broker mqtt disconnect
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show mqtt_iiot_telemetry.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly mqtt_iiot_telemetry.frasm mqtt_iiot_telemetry.pcap
frameassembly mqtt_iiot_telemetry.frasm mqtt_iiot_telemetry.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse mqtt_iiot_telemetry.pcap mqtt_iiot_telemetry_edited.frasm

All mqtt Keywords & Header Options

Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after mqtt:

src_host -> dst_host mqtt [connect | connack | publish | puback | subscribe | suback | pingreq | pingresp | disconnect | pkttype "<text>"] [clientid "<text>"] [topic "<text>"] [qos <0..2>] [retain] [pktid <0..65535>] [keepalive <0..65535>] [returncode <0..255>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
connect | connack | publish | puback | subscribe | suback | pingreq | pingresp | disconnectMQTT Control Packet type (or pkttype "<text>")publishSets the upper 4-bit Control Packet Type (1..14) in byte 0 of the MQTT header.
clientid "<text>" | keepalive <0..65535>Quoted Client ID + keepalive seconds on connectclientid "frameassembly", keepalive 60Populates the CONNECT payload Client Identifier and Keep Alive timer.
topic "<text>"Quoted slash-delimited MQTT topic ("sensors/temp")"sensors/temp"Encodes the 2-byte length-prefixed Topic Name in publish or Topic Filter in subscribe.
qos <0..2> | retainQoS delivery level (0, 1, or 2) + retain flagqos 0, retain offSets QoS bits 1..2 and Retain bit 0 in the Fixed Header.
pktid <0..65535>16-bit Packet Identifier1 (when qos > 0 or subscribe/puback)Matches publish <-> puback and subscribe <-> suback.
returncode <0..255>CONNACK return code (0 Accepted, 4 Bad user/pass, 5 Not authorized)0 (Connection Accepted)Sets byte 3 (Connect Return Code) of connack.

Cross-Layer Wrappers Valid with mqtt

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

11 options
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back).
payload "<text>" | hexpayload "<hex>"Quoted text or hex bytes (choose one)OmittedAppends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums.
srcmac <mac> | dstmac <mac>Colon, hyphen, or Cisco dot MACHost MAC / RFC multicast MACOverrides the 14-byte Ethernet II source or destination MAC address for this single packet.
vlan <0..4095> [pcp <0..7>] [dei <0|1>]VLAN ID 0..4095, PCP 0..7, DEI 0..1UntaggedWraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority.
qinq <0..4095> [innervlan <0..4095>]Outer S-VLAN 0..4095, Inner C-VLAN 0..4095Untagged (innervlan 1 when qinq is set)Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100).
mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>]Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255Unlabeled (at most 1 mpls tag per packet)Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header.
ttl <0..255> [dscp <0..63>] [ecn <0..3>]TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3ttl 64, dscp 0, ecn 0Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings.
ipid <0..65535> [df] [mf] [fragoffset <0..8191>]IPv4 ID, DF/MF flags, fragment offset 0..8191ipid 1, flags 0, fragoffset 0Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6).
flowlabel <0..1048575>20-bit IPv6 Flow Label (0..1048575)0Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), TCP 1883Overrides source or destination port and remembers the port pair automatically on <- replies.
seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rstTCP sequence/ack numbers, window size, flags & RFC 7323 optionspsh ack, win 65535, automatic TCP seq/acknumOverrides automatic TCP sequence tracking, flags, or RFC 7323 options (mss, wscale, sackperm, tsval, tsecr).

Gotchas & Quick Fixes

QoS Maximum Value Is 2 (0, 1, or 2)

Avoid
edge_gw -> broker mqtt publish topic "a/b" qos 3
Valid v3.1.2 Syntax
edge_gw -> broker mqtt publish topic "a/b" qos 1 pktid 10

MQTT reserves QoS 3 (0b11) as a protocol violation ( Malformed Packet); valid levels are 0, 1, and 2.

Field Guide 03
Poke Stateful Firewalls, Suricata, Zeek & OT Conduits