modbusModbus TCP / UDP Industrial Application ProtocolAudit Port 502 PLC Read/Write Rules With Zero Risk of Stopping a Real Pump (modbus)
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.
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 ID0,unitid 1, and computes the 16-bit MBAPLength(unitid + PDU bytes) automatically. - Formats client Request PDUs (
addr+count/value) by default, and switches to PLC Response PDUs (byte_count+ register/coil values) whenisresponseis set. - Translates
writesinglecoil value 1into the standard Modbus0xff00(ON) coil value automatically.
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.
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}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect 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 ID | txid 1, protoid 0, unitid 1 | Populates 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 value | addr 0, count 1, value 0 | Populates register addresses, counts, and 16-bit data words. |
| isresponse | Keyword flag on PLC replies | Request format when omitted | Formats FC 1..4 packets as PLC responses ([FC][ByteCount][Data...]) so Wireshark dissects the reply without malformed-length warnings. |
| transport <tcp|udp> | tcp or udp | tcp | Switches 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
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
| Option | Range / Format | Default | Effect on Packet |
|---|---|---|---|
| wait <number><ns|us|ms|s|m> | Time gap (ns, us, ms, s, m) | 10ms | Advances 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) | Omitted | Appends 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 MAC | Host MAC / RFC multicast MAC | Overrides 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..1 | Untagged | Wraps 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..4095 | Untagged (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..255 | Unlabeled (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..3 | ttl 64, dscp 0, ecn 0 | Sets 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..8191 | ipid 1, flags 0, fragoffset 0 | Sets 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) | 0 | Sets 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..65535 | srcport 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 tcp | Switches Layer 4 transport between TCP (psh ack + length framing where required) and UDP. |
| seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rst | TCP sequence/ack numbers, window size, flags & RFC 7323 options | psh ack, win 65535, automatic TCP seq/acknum | When 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)
scada_hmi <- plc_pump1 modbus readholdingregisters txid 1 count 2 value 1500scada_hmi <- plc_pump1 modbus readholdingregisters txid 1 count 2 value 1500 isresponseModbus 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.