Protocol 29 of 81Layer 4FrameAssembly v3.1.2
llms-full.txt
tcpTransmission Control Protocol & RFC 7323 Options

Stateful 3-Way Handshakes, RFC 7323 Options & Intentional Chaos (tcp)

Default Port / Protocol
IP Proto 6 (Default dstport 80)
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
tcp
Standards & Specs
RFC 9293, RFC 7323, RFC 2018
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP & RFC 7323 (IP Proto 6 (Default dstport 80))

What It Does on the Wire

The crown jewel of the compiler: declare srcport and dstport once on tcp syn, and FrameAssembly tracks seq and acknum across ->, <-, and every TCP Layer 7 protocol (unless you override seq to inject chaos on purpose).

Transmission Control Protocol (tcp, IP protocol 6, RFC 9293) is the connection-oriented Layer 4 transport powering HTTP, TLS, BGP, SSH, databases, and industrial protocols. FrameAssembly includes a built-in stateful 4-tuple TCP sequence tracker shared automatically across raw tcp frames and every TCP-carried Layer 7 protocol.

Once you open a connection with srcport and dstport on tcp syn, subsequent <- and -> statements inherit the reversed port pair, advance seq and acknum by +1 on syn/fin and +payload.len() on data segments, pad RFC 7323 options (mss, wscale, sackperm, tsval, tsecr) to 32-bit boundaries with NOP/EOL bytes, and compute the exact IPv4 or IPv6 pseudo-header checksum.

Stateful Firewall & SYN-Cookie / Window-Scale Inspection

Test NGFW state tables, asymmetric routing drops, TCP timestamp PAWS checks, and RFC 7323 window scaling (wscale 7, sackperm, mss 1460) in Wireshark.

IDS/NDR Retransmission, Out-of-Order & RST Injection Testing

Override seq and acknum explicitly on targeted segments to model overlapping TCP segments, blind rst teardown, or urg/ece/cwr flag edge cases for Suricata and Zeek.

Pre-Handshake Setup Before L7 Application Protocols

Prepend a realistic 3-way tcp handshake ahead of http, tls, bgp, smb, mysql, or modbus frames—the L7 frames automatically continue the exact TCP sequence numbers.

Minimal Quickstart (tcp_quickstart.frasm)

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

tcp_quickstart.frasm8 lines
Open in Playground
host client { ip 10.10.1.15 }
host server { ip 10.10.1.80 }
compile {
client -> server tcp syn srcport 52400 dstport 443 win 65535 mss 1460 wscale 7 sackperm wait 1ms
client <- server tcp syn ack win 65535 mss 1460 wscale 7 sackperm wait 1ms
client -> server tcp ack
}

What the Compiler Calculates So You Don't Have To

  • Tracks 4-tuple (src_ip, dst_ip, src_port, dst_port) sequence state starting at seq 1000—advancing seq by +1 for syn/fin and +payload_len for data without manual arithmetic.
  • Remembers srcport 52400 and dstport 443 from the opening syn so <- and -> follow-up frames swap 443 <-> 52400 automatically.
  • Aligns variable-length TCP options (mss 4B, sackperm 2B, tsval/tsecr 10B, wscale 3B) to 4-byte multiples with RFC 9293 NOP (0x01) padding and updates Data Offset.
Multi-Frame Lab · Ready to Compile

Full Lifecycle: RFC 7323 Handshake, ECN-Capable Data Exchange & Graceful FIN Close

Captures a complete 7-packet TCP lifecycle with RFC 7323 timestamps (tsval/tsecr), selective ACK permission (sackperm), payload push (psh ack), and 4-way fin ack teardown.

tcp_rfc7323_lifecycle.frasm18 lines
Open in Playground
host app_client { ip 172.16.20.10 }
host api_origin { ip 172.16.20.90 }
compile {
// 1. 3-way handshake negotiating MSS 1460, Window Scale 7, SACK, and Timestamps
app_client -> api_origin tcp syn srcport 54110 dstport 8443 win 65535 mss 1460 wscale 7 sackperm tsval 1000 tsecr 0 wait 1ms
app_client <- api_origin tcp syn ack win 65535 mss 1460 wscale 7 sackperm tsval 5000 tsecr 1000 wait 1ms
app_client -> api_origin tcp ack tsval 1001 tsecr 5000 wait 2ms
// 2. Bidirectional application payload (seq/acknum advance automatically by byte length)
app_client -> api_origin tcp psh ack tsval 1003 tsecr 5000 payload "PING /healthz
" wait 2ms
app_client <- api_origin tcp psh ack tsval 5002 tsecr 1003 payload "200 OK
" wait 3ms
// 3. Clean 3-packet FIN/ACK session close
app_client -> api_origin tcp fin ack tsval 1006 tsecr 5002 wait 1ms
app_client <- api_origin tcp fin ack tsval 5003 tsecr 1007 wait 1ms
app_client -> api_origin tcp ack tsval 1007 tsecr 5004
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show tcp_rfc7323_lifecycle.frasm

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

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

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

src_host -> dst_host tcp [syn] [ack] [fin] [rst] [psh] [urg] [ece] [cwr] [srcport <0..65535>] [dstport <0..65535>] [seq <number>] [acknum <number>] [win|window <0..65535>] [urgent <0..65535>] [mss <0..65535>] [wscale <0..255>] [sackperm] [tsval <number>] [tsecr <number>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
syn | ack | fin | rst | psh | urg | ece | cwrBare lowercase flag keywords (combinable)ack (or psh ack when payload present)Sets individual control bits in byte 13 of the 20-byte TCP header.
srcport <0..65535> | dstport <0..65535>Whole number (0..65535)srcport 49152, dstport 80 (or inherited)Sets TCP source and destination ports and anchors bidirectional pair port memory.
seq <number> | acknum <number>Whole numberTracked 4-tuple state (initial seq 1000)Explicitly overrides the 32-bit Sequence Number or Acknowledgment Number (acknum) and updates tracker state.
win <0..65535> | window <0..65535>Whole number (0..65535)65535Sets the 16-bit Receive Window field (window is an exact alias for win).
urgent <0..65535>Whole number (0..65535)0Sets the 16-bit Urgent Pointer field (pair with the urg flag).
mss <0..65535>Whole number (0..65535) (bytes)OmittedAppends TCP Option Kind 2 (Maximum Segment Size, 4 bytes, e.g. 1460 IPv4 or 1440 IPv6).
wscale <0..255>8-bit shift count (RFC 7323 <= 14)OmittedAppends TCP Option Kind 3 (Window Scale, 3 bytes + 1-byte alignment NOP).
sackpermBoolean flag keywordOmittedAppends TCP Option Kind 4 (SACK Permitted, 2 bytes) per RFC 2018.
tsval <number> [tsecr <number>]Whole numberOmitted (tsecr 0 when only tsval set)Appends TCP Option Kind 8 (RFC 7323 Timestamps, 10 bytes + 2-byte alignment NOPs).

Cross-Layer Wrappers Valid with tcp

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

9 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).

Gotchas & Quick Fixes

Use acknum <number> for the Acknowledgment Number (Bare ack Is the Flag)

Avoid
client -> server tcp syn ack 1001 sport 50000 dport 443
Valid v3.1.2 Syntax
client -> server tcp syn ack acknum 1001 srcport 50000 dstport 443

Bare ack sets the 1-bit ACK flag in the TCP header. Use acknum <number> to set the 32-bit Acknowledgment Number, and always spell out srcport / dstport.

Never Add Underscores to sackperm or TCP Flags

Avoid
client -> server tcp flags [SYN] sack_perm
Valid v3.1.2 Syntax
client -> server tcp syn sackperm

Every FrameAssembly v3.1.2 built-in keyword is strictly lowercase alphanumeric (syn, ack, psh, sackperm, wscale, tsval, tsecr) without brackets or underscores.

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