Protocol 76 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
modbusModbus TCP / UDP Industrial Application Protocol

Audit Port 502 PLC Read/Write Rules With Zero Risk of Stopping a Real Pump (modbus)

Default Port / Protocol
TCP 502 (or UDP 502 via transport udp)
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
mbtcp || modbus
Standards & Specs
Modbus Application Protocol v1.1b3
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP 502 (or UDP 502 via transport udp) (transport tcp|udp)Modbus TCP

What It Does on the Wire

Modbus has zero authentication: anyone who can reach TCP 502 can flip coils. Craft readholdingregisters (FC 3), writesinglecoil (FC 5), and isresponse PLC replies offline without making the plant manager sweat.

Modbus TCP (modbus) is the most widely deployed industrial protocol connecting SCADA HMIs, historians, VFDs, smart breakers, and PLCs over TCP port 502 (with transport udp available for Modbus-over-UDP gateways). Because Modbus has zero built-in authentication, industrial firewalls (Palo Alto, Fortinet, Tofino/Hirschmann) and OT IDS platforms (Claroty, Nozomi, Dragos, Suricata, Zeek) inspect every 7-byte MBAP header + Function Code to allow safe read polling (FC 1..4) while alerting on or blocking write commands (FC 5, 6, 15, 16).

FrameAssembly builds exact MBAP headers (txid, protoid 0, length, unitid) and Modbus request or PLC reply (isresponse) PDUs completely offline—without ever touching live plant equipment.

Test OT Firewall Read-Only Conduit Rules (Allow FC 3/4, Block FC 5/6/16)

Generate readholdingregisters (FC 3) alongside writesingleregister (FC 6) and writesinglecoil (FC 5) .pcap files to verify deep-packet industrial firewall rules.

Validate Claroty, Nozomi, Dragos & Suricata Modbus Signatures

Replay unauthorized engineering-workstation register writes or illegal unit ID scans into OT NDR span sensors safely.

Troubleshoot SCADA Poll/Response Byte Counts With isresponse

Add isresponse on <- PLC replies so FrameAssembly formats [Function Code][Byte Count][Register Data] instead of a client request PDU.

Minimal Quickstart (modbus_quickstart.frasm)

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

modbus_quickstart.frasm10 lines
Open in Playground
host scada_hmi { ip 192.168.100.10 }
host plc_pump1 { ip 192.168.100.50 }
compile {
scada_hmi -> plc_pump1 tcp syn srcport 50502 dstport 502 wait 1ms
scada_hmi <- plc_pump1 tcp syn ack wait 1ms
scada_hmi -> plc_pump1 tcp ack wait 1ms
scada_hmi -> plc_pump1 modbus readholdingregisters txid 1 unitid 1 addr 100 count 2 wait 3ms
scada_hmi <- plc_pump1 modbus readholdingregisters txid 1 unitid 1 count 2 value 1500 isresponse
}

What the Compiler Calculates So You Don't Have To

  • Defaults to TCP destination port 502 (psh ack), Protocol ID 0, unitid 1, and computes the 16-bit MBAP Length (unitid + PDU bytes) automatically.
  • Formats client Request PDUs (addr + count / value) by default, and switches to PLC Response PDUs (byte_count + register/coil values) when isresponse is set.
  • Translates writesinglecoil value 1 into the standard Modbus 0xff00 (ON) coil value automatically.
Multi-Frame Lab · Ready to Compile

Normal Historian Read Polling (FC 3) + Unauthorized Coil/Register Write (FC 5 / FC 6)

Models an HMI polling Holding Registers on Unit 1 (FC 3 request + isresponse reply), followed by a writesinglecoil (FC 5) and writesingleregister (FC 6) command to test OT write-detection alarms.

modbus_ot_conduit_test.frasm15 lines
Open in Playground
host hmi_01 { ip 10.100.10.15 }
host vfd_plc { ip 10.100.20.50 }
compile {
hmi_01 -> vfd_plc tcp syn srcport 51502 dstport 502 win 65535 mss 1460 wait 1ms
hmi_01 <- vfd_plc tcp syn ack win 65535 mss 1460 wait 1ms
hmi_01 -> vfd_plc tcp ack wait 1ms
// 1. Authorized Read Holding Registers (FC 3) + PLC Response (isresponse)
hmi_01 -> vfd_plc modbus readholdingregisters txid 101 unitid 1 addr 0 count 4 wait 2ms
hmi_01 <- vfd_plc modbus readholdingregisters txid 101 unitid 1 count 4 value 3600 isresponse wait 5ms
// 2. Write Single Coil (FC 5) & Write Single Register (FC 6) -> triggers OT IDS write alert!
hmi_01 -> vfd_plc modbus writesinglecoil txid 102 unitid 1 addr 10 value 1 wait 2ms
hmi_01 <- vfd_plc modbus writesinglecoil txid 102 unitid 1 addr 10 value 1 isresponse wait 3ms
hmi_01 -> vfd_plc modbus writesingleregister txid 103 unitid 1 addr 200 value 1800
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show modbus_ot_conduit_test.frasm

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

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

All modbus 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 modbus:

src_host -> dst_host modbus [readcoils | readdiscreteinputs | readholdingregisters | readinputregisters | writesinglecoil | writesingleregister | writemultipleregisters | func "<name_or_fc>"] [txid <0..65535>] [protoid <0..65535>] [unitid <0..255>] [addr <0..65535>] [count <0..65535>] [value <0..65535>] [isresponse] [transport <tcp|udp>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
readcoils | readdiscreteinputs | readholdingregisters | readinputregisters | writesinglecoil | writesingleregister | writemultipleregisters | func "<fc>"Function Code keyword or number ("1", "2", "3", "4", "5", "6", "15", "16")readholdingregisters (FC 3)Sets the 1-byte Modbus Function Code immediately after unitid.
txid <0..65535> | protoid <0..65535> | unitid <0..255>MBAP Transaction ID, Protocol ID (0 = Modbus), and Slave/Unit IDtxid 1, protoid 0, unitid 1Populates the 7-byte MBAP header preceding the Modbus PDU.
addr <0..65535> | count <0..65535> | value <0..65535>0-indexed starting register/coil address, item quantity, and write/reply valueaddr 0, count 1, value 0Populates register addresses, counts, and 16-bit data words.
isresponseKeyword flag on PLC repliesRequest format when omittedFormats FC 1..4 packets as PLC responses ([FC][ByteCount][Data...]) so Wireshark dissects the reply without malformed-length warnings.
transport <tcp|udp>tcp or udptcpSwitches between Modbus TCP (502) and Modbus UDP (502).

Cross-Layer Wrappers Valid with modbus

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

12 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 502 (or UDP 502 via transport udp)Overrides source or destination port and remembers the port pair automatically on <- replies.
transport <tcp|udp>tcp or udp (supported on 9 dual-L4 protocols)transport tcpSwitches Layer 4 transport between TCP (psh ack + length framing where required) and UDP.
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/acknumWhen using TCP (transport tcp or default TCP): overrides automatic TCP sequence tracking, flags, or mss/wscale/sackperm/tsval/tsecr.

Gotchas & Quick Fixes

Add isresponse on <- PLC Replies to Read Requests (FC 1..4)

Avoid
scada_hmi <- plc_pump1 modbus readholdingregisters txid 1 count 2 value 1500
Valid v3.1.2 Syntax
scada_hmi <- plc_pump1 modbus readholdingregisters txid 1 count 2 value 1500 isresponse

Modbus uses the same Function Code (0x03) for both requests and responses, with different wire layouts. Adding isresponse emits the PLC’s Byte Count + Register Values reply structure.

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