FrameAssembly (frameassembly) — Create Custom .pcap Packet Captures from Plain Text Without Root or Programming Experience

Copy-Paste Packet Recipes • The 3-Step Mental Model • Terminal Ladder (frameassembly show) • Multi-Platform Install • Wireshark Cheat Sheet • Common Mistakes • All 81 Protocols • FAQ & Disambiguation • Documentation

FrameAssembly (frameassembly v1.4.1) is a rootless, offline "Packets as Code" ("PCAP as Code") packet generator and compiler that turns a plain-text packet recipe (.fasm, media type text/vnd.frameassembly) into a deterministic .pcap / .pcapng packet capture file across 81 network protocols spanning Layers 2 through 7—with no libpcap or raw sockets required.

It is built for network technicians, firewall engineers, Linux system administrators, NOC/SOC analysts, and OT/SCADA integrators who want a Scapy alternative without Python, without clicking through GUI stream dialogs in Ostinato, and without fighting raw hexadecimal byte offsets in text2pcap. Positioned as the upstream companion compiler to your analysis and replay tools, you simply list the devices in your scenario, write one line per packet using everyday networking terms (VLAN 100, TCP SYN, DSTPORT 443, DSCP 46, SNMP3 TRAP), and FrameAssembly automatically builds the Ethernet/IPv4/IPv6/TCP/UDP/SCTP headers, calculates lengths and checksums, swaps ports on reply packets (<-), and tracks TCP SEQ/ACK numbers—producing a clean, zero-noise .pcap file ready to open in Wireshark / tshark, feed into Suricata / Zeek, or transmit onto a live network port with tcpreplay.

Copy-Paste Packet Recipes for Common Network Tasks

Create Custom .pcap Captures from Plain Text (No Root Permissions or Programming Experience Required)

Generate a test capture without setting up a Python environment for Scapy, calculating raw hex offsets in text2pcap, or needing sudo raw-socket permissions. Write your hosts and packet lines in plain text and compile directly to .pcap in user space:

host client { ip 10.0.0.10 mac 00:11:22:33:44:55 }
host server { ip 10.0.0.80 mac aa:bb:cc:dd:ee:ff }

flow web_session(c, s) {
    c -> s tcp syn srcport 51234 dstport 80 win 65535 mss 1460 wait 1ms
    c <- s tcp syn ack win 65535 mss 1460 wait 1ms
    c -> s tcp ack wait 1ms
    c -> s http get uri "/index.html" host_hdr "example.com" wait 5ms
    c <- s http status 200 reason "OK" body "<h1>Hello</h1>" wait 2ms
}

compile {
    web_session(client, server)
}

$ frameassembly web.fasm -o web.pcap && frameassembly show web.fasm

Test SNMPv1/v2c & Encrypted SNMPv3 Trap Receivers

Verify Zabbix, SolarWinds, LibreNMS, PRTG, or snmptrapd alerting rules without waiting for a switch power supply or BGP peer to fail. FrameAssembly generates SNMPv1/v2c polls and encrypted SNMPv3 authPriv (SHA-256 + AES-128) traps with standard RFC 3414/3826/7860 cryptography out of the box:

host core_switch { ip 10.10.1.2  mac 00:1a:2b:3c:4d:01 }
host nms_server  { ip 10.10.1.50 mac 00:1a:2b:3c:4d:50 }

flow snmp_alert_and_poll(sw, nms) {
    sw -> nms vlan 100 snmp3 trap user "netops" engineid "80001f8801" engineboots 5 enginetime 3600 auth sha256 "AuthPass123!" priv aes "PrivPass123!" oid 1.3.6.1.6.3.1.1.5.3 varbind 1.3.6.1.2.1.2.2.1.8.1 int 2 wait 5ms
    nms -> sw vlan 100 snmp2 get community "noc_ro" reqid 101 varbind 1.3.6.1.2.1.1.5.0 null wait 2ms
    nms <- sw vlan 100 snmp2 response community "noc_ro" reqid 101 varbind 1.3.6.1.2.1.1.5.0 string "core-sw-01.dc1" wait 2ms
}

compile {
    snmp_alert_and_poll(core_switch, nms_server)
}

$ frameassembly snmp_test.fasm -o snmp_test.pcap && tshark -r snmp_test.pcap

Craft 802.1Q VLAN, 802.1ad QinQ, MPLS & DSCP QoS Packets

Desktop OS network stacks and NIC drivers often strip 802.1Q tags on capture and block raw-socket injection of carrier QinQ double tags or custom DiffServ markings. FrameAssembly writes VLAN <id> PCP <0..7>, QINQ <s_vid> INNER_VLAN <c_vid>, MPLS <label> EXP <0..7>, and DSCP <0..63> headers directly into the .pcap file:

host branch_cpe { ip 10.220.1.10  mac 00:50:56:c0:01:10 }
host hq_gateway { ip 10.220.1.200 mac 00:50:56:c0:01:c8 }

flow metro_qos_and_tls(cpe, hq) {
    cpe -> hq vlan 110 pcp 5 dei 0 dscp 46 rtp pt 0 seq 1 timestamp 160 ssrc 0x10203040 payload "G711_VOICE" wait 5ms
    cpe -> hq qinq 2000 inner_vlan 150 pcp 6 mpls 40960 exp 6 bos 1 mpls_ttl 64 dscp 46 ttl 64 tls client_hello sni "vault.hq.example.com" ciphersuite 4866 alpn "h2" wait 5ms
    cpe <- hq qinq 2000 inner_vlan 150 pcp 6 mpls 40960 exp 6 bos 1 mpls_ttl 63 dscp 46 ttl 63 tls server_hello ciphersuite 4866 alpn "h2" wait 5ms
}

compile {
    metro_qos_and_tls(branch_cpe, hq_gateway)
}

$ frameassembly qos.fasm -o qos.pcap && wireshark qos.pcap &

Validate Firewall ACLs & Suricata / Zeek IDS Rules

Stateful firewalls and IDS/IPS engines drop isolated packets that lack a valid 3-way TCP handshake or sequence progression. FrameAssembly tracks TCP sequence numbers and reply ports automatically across permitted handshakes, blocked port RST ACK rejections, and ICMP Administratively Prohibited replies:

host dmz_scanner { ip 172.16.99.9 mac 00:1a:2b:3c:4d:09 }
host target_fw   { ip 10.10.1.1   mac 00:1a:2b:3c:4d:01 }

flow firewall_acl_test(scanner, fw) {
    scanner -> fw vlan 200 tcp syn srcport 54320 dstport 443 win 64240 mss 1460 wait 1ms
    scanner <- fw vlan 200 tcp syn ack win 65535 mss 1460 wait 1ms
    scanner -> fw vlan 200 tcp ack wait 2ms
    scanner -> fw vlan 200 tcp syn srcport 54321 dstport 22 win 64240 wait 1ms
    scanner <- fw vlan 200 tcp rst ack wait 2ms
    scanner -> fw vlan 200 ttl 64 icmp echo_request id 500 seq 1 payload "ACL_PING_TEST" wait 1ms
    scanner <- fw vlan 200 ttl 64 icmp dest_unreach code 13
}

compile {
    firewall_acl_test(dmz_scanner, target_fw)
}

$ frameassembly firewall.fasm -o firewall.pcap && suricata -r firewall.pcap -k none

Build Sanitized Reproducer Captures for Vendor TAC Tickets & CI

Instead of scrubbing live production captures for vendor support tickets (Cisco TAC, Juniper JTAC, Arista) or CI tests—and risking leaked internal IPs or customer data—build a clean, zero-noise reproducer using RFC 5737 documentation subnets (192.0.2.0/24, 198.51.100.0/24):

host branch_gw { ip 192.0.2.1     mac 00:11:22:aa:bb:01 }
host auth_srv  { ip 198.51.100.10 mac 00:11:22:cc:dd:10 }

flow tac_sanitized_radius(gw, srv) {
    gw -> srv radius access_request user "redacted_user" nas_ip 192.0.2.1 wait 10ms
    gw <- srv radius access_accept wait 5ms
    gw -> srv syslog facility 1 severity 6 hostname "branch-gw" app "tacacs" msg "User authenticated via 802.1X"
}

compile {
    tac_sanitized_radius(branch_gw, auth_srv)
}

$ frameassembly tac_repro.fasm -o tac_repro.pcap && frameassembly show tac_repro.fasm

Test Industrial OT / SCADA Firewalls (Modbus, DNP3, S7comm, BACnet, OPC UA)

Test industrial firewall conduits and OT security sensors without physical PLCs or vendor engineering workstations. Generate Modbus TCP, IEEE 1815 DNP3 (with automatic CRC-16), Siemens S7comm, BACnet/IP, EtherNet/IP, and OPC UA traffic directly on your laptop:

host scada_hmi { ip 192.168.100.10 mac 00:1b:21:a0:00:10 }
host plant_plc { ip 192.168.100.50 mac 00:0e:8c:a0:00:50 }

flow ot_firewall_test(hmi, plc) {
    hmi -> plc vlan 110 modbus read_holding_registers txid 1 unitid 1 addr 40001 count 2 wait 2ms
    hmi <- plc vlan 110 modbus read_holding_registers txid 1 unitid 1 count 2 is_response wait 2ms
    hmi -> plc vlan 110 dnp3 read src 1 dst 10 group 60 variation 1 wait 2ms
    hmi -> plc vlan 110 s7comm setup_comm rosctr "JOB" pdu_ref 101 wait 2ms
    hmi -> plc vlan 110 bacnet read_property invoke_id 1 object_type 0 object_instance 1 property_id 85 wait 2ms
    hmi -> plc vlan 110 opcua msg_type "HEL" chunk_type "F" endpoint_url "opc.tcp://192.168.100.50:4840"
}

compile {
    ot_firewall_test(scada_hmi, plant_plc)
}

$ frameassembly ot_test.fasm -o ot_test.pcap && tshark -r ot_test.pcap

Comparison Matrix: FrameAssembly vs. Traditional Tools

The 3-Step Mental Model for Network Engineers

Every .fasm file is structured in three logical steps that mirror how network technicians diagram traffic:

┌────────────────────────────────────────────────────────────────────────┐
│                      The 3-Step Mental Model                           │
├───────────────────┬───────────────────────────────┬────────────────────┤
│ 1. HOST           │ 2. FLOW                       │ 3. COMPILE         │
│ Declare endpoints │ Define the packet sequence    │ Emit the .pcap     │
│ IP & optional MAC │ 1 statement = 1 wire frame    │ Wire hosts to flow │
│ (v4, v6, any MAC) │ -> forward, <- reply (swaps)  │ Single or loop N   │
└───────────────────┴───────────────────────────────┴────────────────────┘

1. Step 1: Declare Endpoints with HOST: Give friendly names to your IPv4 or IPv6 endpoints. FrameAssembly natively accepts Linux colon (00:1a:2b:3c:4d:5e), Windows hyphen (00-1A-2B-3C-4D-5E), and Cisco dotted-quad (001a.2b3c.4d5e) MAC addresses. If you omit the MAC, FrameAssembly assigns clean unicast MACs or derives standard RFC 1112 / RFC 2464 multicast MACs automatically.
2. Step 2: Define Packet Sequences with FLOW: Write traffic patterns between placeholder endpoints (c, s). Every statement inside a FLOW block generates exactly one Ethernet frame. Using c -> s marks a forward request; using c <- s marks a reverse response that automatically swaps source and destination ports.
3. Step 3: Build the Capture with COMPILE: Connect your declared hosts into your flow templates. A single flow can be executed once or repeated across multiple host pairs and loop <count> iterations.

Visual Packet Ladders & Terminal Inspection (frameassembly show)

FrameAssembly aligns directly with Wireshark's Flow Graph ladder view:

  Wireshark Flow Graph               FrameAssembly .fasm Flow Statement
--------------------------------------------------------------------------------------
  10.0.0.10             10.0.0.80
      |                     |
      |   TCP 51234 -> 80   |
      |-------------------->|        c -> s tcp syn srcport 51234 dstport 80 win 65535
      |        [SYN]        |
      |                     |
      |   TCP 80 -> 51234   |
      |<--------------------|        c <- s tcp syn ack win 65535 wait 1ms
      |      [SYN, ACK]     |
      |                     |
      |   TCP 51234 -> 80   |
      |-------------------->|        c -> s tcp ack wait 1ms
      |        [ACK]        |
      |                     |
      |  HTTP GET /index    |
      |-------------------->|        c -> s http get uri "/index.html" host_hdr "example.com"
      |      [PSH, ACK]     |
      |                     |
      |   HTTP 200 OK       |
      |<--------------------|        c <- s http status 200 reason "OK" body "<h1>Hello</h1>"
      |      [PSH, ACK]     |

Inspecting Frames in Terminal Without Writing Files

Use frameassembly show <file.fasm> to inspect your generated ladder directly in your terminal without touching the disk:

$ frameassembly show demo.fasm
#      Time (ms)   Source -> Destination                    Proto       Bytes  Summary
--------------------------------------------------------------------------------------------------------------
1      0.000       10.0.0.10 -> 10.0.0.80                   TCP         58     51234 -> 80 [SYN] seq=1000 len=0
2      1.000       10.0.0.80 -> 10.0.0.10                   TCP         58     80 -> 51234 [SYN ACK] seq=2000 ack=1001 len=0
3      2.000       10.0.0.10 -> 10.0.0.80                   TCP         54     51234 -> 80 [ACK] seq=1001 ack=2001 len=0
4      3.000       10.0.0.10 -> 10.0.0.80                   HTTP        97     51234 -> 80 [ACK PSH] seq=1001 ack=2001 len=43
5      8.000       10.0.0.80 -> 10.0.0.10                   HTTP        126    80 -> 51234 [ACK PSH] seq=2001 ack=1044 len=72

To compile to a .pcap capture file:

$ frameassembly demo.fasm -o output.pcap
Successfully parsed 2 hosts, 1 flows
Starting PCAP compilation...
Successfully generated output.pcap (5 frames, 393 bytes, duration 8.000 ms)

You can then inspect the output in Wireshark or replay it on a live network port with tcpreplay:

# Inspect in Wireshark or tshark
tshark -r output.pcap
wireshark output.pcap &

# Replay onto a live interface or firewall test port
sudo tcpreplay -i eth0 output.pcap

Multi-Platform Installation

Install FrameAssembly using your platform's standard package manager:

Common Syntax Mistakes & Plain-English Error Messages

FrameAssembly's diagnostic engine provides actionable, plain-English "Did you mean...?" hints designed specifically for network technicians:

From Wireshark / tcpdump to .fasm Translation Table

If you know how to read Wireshark filters or tcpdump expressions, you already know FrameAssembly syntax:

Use ChatGPT, Claude, or Copilot to Write .fasm from Plain English

FrameAssembly publishes a machine-readable reference sheet (llms.txt) specifically optimized for AI coding assistants. Copy and paste the prompt below into ChatGPT, Claude, Microsoft Copilot, or Cursor:

Read the FrameAssembly (.fasm) syntax reference at:
https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/llms.txt

Write a complete, compilable FrameAssembly (.fasm) packet recipe with HOST, FLOW, and COMPILE blocks for the following network scenario:
[Describe your scenario here — for example: "A branch router at 10.10.1.1 sending an encrypted SNMPv3 SHA256 + AES trap to NMS server 10.10.1.50 on VLAN 100, followed by a TCP 3-way handshake and HTTPS TLS 1.3 ClientHello to vault.example.com"]

Rules to follow:
- Use only canonical HOST <id> { IP <ip> [MAC <mac>] }, FLOW <id>(<params>) { ... }, and COMPILE { ... } blocks.
- Use SRCPORT, DSTPORT, ACKNUM, bare TCP flag names (SYN ACK), and trailing WAIT <n><ms|s|us|ns>.
- Output only the compilable .fasm file.

Universal Layer 2–4 Modifiers

Any packet line can attach Layer 2 trunk tags, Layer 3 QoS/fragmentation headers, Layer 4 port/TCP options, raw payloads, and capture timestamps alongside any protocol:

Supported Protocols & Default Wire Behavior

Every protocol works out of the box with standard RFC defaults when optional fields are omitted:

Exhaustive Protocol & Sub-Keyword Reference (All 81 Protocols)

1. Layer 2 Switching & Data-Link Protocols (8 Protocols — docs/l2_protocols.md)

• examples/l2/arp/ — ARP (RFC 826 / RFC 5227): REQUEST, REPLY, GRATUITOUS / GARP, SHA <mac> / SENDERMAC <mac>, SPA <ip> / SENDERIP <ip>, THA <mac> / TARGETMAC <mac>, TPA <ip> / TARGETIP <ip>.
• examples/l2/vlan/ — VLAN (IEEE 802.1Q): VLAN <1..4094>, PCP <0..7>, DEI <0..1>.
• examples/l2/qinq/ — QINQ (IEEE 802.1ad Provider Bridging): QINQ <1..4094>, INNER_VLAN <1..4094>, PCP <0..7>, DEI <0..1>.
• examples/l2/lldp/ — LLDP (IEEE 802.1AB): CHASSIS_ID "<str>", PORT_ID "<str>", TTL <u16>, SYSNAME "<str>", SYSDESC "<str>".
• examples/l2/stp/ — STP (IEEE 802.1D / 802.1w RSTP): RSTP, ROOT_ID "<prio>/<mac>" / ROOTID "<str>", BRIDGE_ID "<prio>/<mac>" / BRIDGEID "<str>", COST <u32>, PORT_ID <u16>, MAX_AGE <u16>, HELLO_TIME <u16>, FORWARD_DELAY <u16>, FLAGS <u8>.
• examples/l2/lacp/ — LACP (IEEE 802.3ad): ACTOR_SYS <mac>, ACTOR_KEY <u16>, ACTOR_PORT <u16>, ACTOR_STATE <u8>, PARTNER_SYS <mac>, PARTNER_KEY <u16>, PARTNER_PORT <u16>, PARTNER_STATE <u8>.
• examples/l2/eapol/ — EAPOL (IEEE 802.1X NAC): VERSION <u8>, TYPE <START|LOGOFF|KEY|EAP_PACKET>, EAP_CODE <u8>, EAP_ID <u8>, EAP_METHOD <u8>, IDENTITY "<str>".
• examples/l2/mpls/ — MPLS (RFC 3032): MPLS <label> / LABEL <u32>, EXP <0..7> / TC <0..7>, BOS <0..1>, MPLS_TTL <u8>.

2. Layer 3 Control, Tunneling, VPN & Routing Protocols (20 Protocols — docs/l3_protocols.md)

• examples/l3/icmp/ — ICMP (RFC 792 / RFC 4443 Dual-Stack): ECHO_REQUEST, ECHO_REPLY, DEST_UNREACH, TIME_EXCEEDED, REDIRECT, TYPE <u8>, CODE <u8>, ID <u16>, SEQ <u16>, GATEWAY <ip>.
• examples/l3/ndp/ — NDP (RFC 4861 IPv6 Neighbor Discovery): ROUTER_SOLICIT, ROUTER_ADVERT, NEIGHBOR_SOLICIT, NEIGHBOR_ADVERT, REDIRECT, TARGET <ipv6>, SLLA <mac>, TLLA <mac>, ROUTER_LIFETIME <u16>.
• examples/l3/igmp/ — IGMP (RFC 2236 / RFC 3376): QUERY, REPORT, LEAVE, V1, V2, V3, VERSION <1..3>, GROUP <ipv4>, MAX_RESP <u8>.
• examples/l3/mld/ — MLD (RFC 2710 / RFC 3810 IPv6 Multicast): QUERY, REPORT, DONE, MULTICAST_ADDR <ipv6>, MAX_RESP_DELAY <u16>.
• examples/l3/gre/ — GRE (RFC 2784 / RFC 2890): CHECKSUM, GRE_KEY <u32>, GRE_SEQ <u32>, GRE_PROTO <u16>.
• examples/l3/vxlan/ — VXLAN (RFC 7348): VNI <0..16777215> / VNID <u32>, SRCPORT <u16>, DSTPORT <u16>.
• examples/l3/geneve/ — GENEVE (RFC 8926): VNI <0..16777215> / VNID <u32>, PROTOCOL_TYPE <u16>, OPT_CLASS <u16>, OPT_TYPE <u8>.
• examples/l3/ipsec/ — IPSEC (RFC 4301): SPI <u32>, SEQ <u32>, IV "<hex>", ICV "<hex>", NEXT_HEADER <u8>.
• examples/l3/esp/ — ESP (RFC 4303): SPI <u32>, SEQ <u32>, IV "<hex>", ICV "<hex>", NEXT_HEADER <u8>.
• examples/l3/ah/ — AH (RFC 4302): SPI <u32>, SEQ <u32>, ICV "<hex>", NEXT_HEADER <u8>.
• examples/l3/ikev2/ — IKEV2 (RFC 7296): SA_INIT, CREATE_CHILD_SA, INFORMATIONAL, EXCHANGE <mode>, INITIATOR_SPI <u64>, RESPONDER_SPI <u64>, MSGID <u32>, FLAGS <u8>, NEXT_PAYLOAD <u8>.
• examples/l3/wireguard/ — WIREGUARD (WireGuard VPN): TYPE <INITIATION|RESPONSE|COOKIE|DATA> (or bare INITIATION, COOKIE, DATA), SENDER <u32>, RECEIVER <u32>, COUNTER <u64>.
• examples/l3/ospf/ — OSPF (RFC 2328 OSPFv2 / RFC 5340 OSPFv3): HELLO, DBD, LSR, LSU, LSACK, ROUTER_ID <ipv4>, AREA_ID <u32>, HELLO_INTERVAL <u16>, DEAD_INTERVAL <u32>, PRIORITY <u8>.
• examples/l3/bgp/ — BGP (RFC 4271 / RFC 2545 BGP-4): OPEN, UPDATE, NOTIFICATION, KEEPALIVE, ASN <u32>, HOLDTIME <u16>, BGPID <ipv4>, PREFIX "<cidr>", NEXTHOP <ip>.
• examples/l3/rip/ — RIP (RFC 2453 RIPv2 / RFC 2080 RIPng): REQUEST, RESPONSE, PREFIX <ip>, NEXTHOP <ip>, METRIC <1..16>, TAG <u16>.
• examples/l3/vrrp/ — VRRP (RFC 5798 VRRPv3 / RFC 3768 VRRPv2): VERSION <2|3>, VRID <1..255>, PRIORITY <0..255>, ADV_INT <u16>, VIP <ip>.
• examples/l3/hsrp/ — HSRP (RFC 2281): GROUP <u8>, PRIORITY <u8>, STATE <u8>, HELLOTIME <u8>, HOLDTIME <u16>, AUTH "<str>", VIP <ip>.
• examples/l3/pim/ — PIM (RFC 7761 PIM-SM): HELLO, JOIN_PRUNE, REGISTER, DR_PRIORITY <u32>, HOLDTIME <u16>, SOURCE <ip>, GROUP <ip>, RP <ip>.
• examples/l3/bfd/ — BFD (RFC 5880 / RFC 5881): STATE <0..3>, DIAG <0..31>, MY_DISC <u32>, YOUR_DISC <u32>, MIN_TX <u32>, MIN_RX <u32>, MULT <u8>.
• examples/l3/openflow/ — OPENFLOW (OpenFlow 1.3): HELLO, FEATURES_REQ, FEATURES_REPLY, PACKET_IN, PACKET_OUT, FLOW_MOD, ECHO_REQ, ECHO_REPLY, VERSION <u8>, XID <u32>, DPID <u64>, TABLE_ID <u8>, PRIORITY <u16>.

3. Layer 4 Transport Protocols (3 Protocols — docs/l4_transports.md)

• examples/l4/tcp/ — TCP (RFC 9293 / RFC 7323): SYN, ACK, FIN, RST, PSH, URG, ECE, CWR, SRCPORT <u16>, DSTPORT <u16>, SEQ <u32>, ACKNUM <u32>, WIN <u16> / WINDOW <u16>, MSS <u16>, WSCALE <u8>, SACK_PERM, TSVAL <u32>, TSECR <u32>, URGENT <u16>.
• examples/l4/udp/ — UDP (RFC 768): SRCPORT <u16>, DSTPORT <u16>, PAYLOAD "<str>", HEXPAYLOAD "<hex>".
• examples/l4/sctp/ — SCTP (RFC 9260): CHUNK <DATA|INIT|INIT_ACK|SACK|HEARTBEAT|HEARTBEAT_ACK|ABORT|SHUTDOWN|COOKIE_ECHO|COOKIE_ACK>, VTAG <u32>, TSN <u32> / SEQ <u32>, STREAM <u16>, SSN <u16>, PPID <u32>.

4. Layer 7 SNMP Protocols (3 Protocols — docs/l7_snmp.md)

• examples/l7/snmp/snmpv1/ — SNMP1 (RFC 1157 SMIv1 BER): TRAP, GET, GETNEXT, SET, RESPONSE, COMMUNITY "<str>", REQID <u32>, OID <oid>, SYSUPTIME <u32>, ENTERPRISE <oid>, AGENTIP <ipv4>, GENTRAP <0..6>, SPECTRAP <u32>, VARBIND.
• examples/l7/snmp/snmpv2c/ — SNMP2 (RFC 3416 SMIv2 BER): TRAP, INFORM, GET, GETNEXT, GETBULK, SET, RESPONSE, COMMUNITY "<str>", REQID <u32>, NONREPEATERS <u32>, MAXREPETITIONS <u32>, SYSUPTIME <u32>, OID <oid>, VARBIND.
• examples/l7/snmp/snmpv3/ — SNMP3 (RFC 3414 / 3826 / 7860 USM): TRAP, INFORM, GET, GETNEXT, GETBULK, SET, RESPONSE, USER "<str>", ENGINEID "<hex>", ENGINEBOOTS <u32>, ENGINETIME <u32>, CONTEXTNAME "<str>", AUTH <MD5|SHA|SHA256|SHA384|SHA512> "<pass>", PRIV <DES|AES> "<pass>", REQID <u32>, NONREPEATERS <u32>, MAXREPETITIONS <u32>, SYSUPTIME <u32>, OID <oid>, VARBIND.
  • All 9 SMI VARBIND <oid> <TYPE> [value] Types: NULL / NULLVAL, STRING "<text>", INT <i32>, TIMETICKS <u32>, IPVAL <ip>, OIDVAL <oid>, COUNTER32 <u32>, GAUGE32 <u32>, COUNTER64 <u64>.

5. Layer 7 Infrastructure, Time, AAA & Flow Telemetry Protocols (11 Protocols — docs/l7_infra_and_telemetry.md)

• examples/l7/dns/ — DNS (RFC 1035): QUERY, RESPONSE, TXID <u16>, QNAME "<domain>", QTYPE "<type>", RDATA "<str>", RCODE <u8>, ANS_TTL <u32>, TRANSPORT TCP.
• examples/l7/mdns/ — MDNS (RFC 6762): QUERY, RESPONSE, TXID <u16>, QNAME "<name>", QTYPE "<type>", RDATA "<str>", RCODE <u8>, ANS_TTL <u32>.
• examples/l7/dhcp/ — DHCP (RFC 2131 / RFC 8415 DHCPv6): DISCOVER, OFFER, REQUEST, ACK, RELEASE, SOLICIT, ADVERTISE, REPLY, XID <u32> / TXID <u32>, CIADDR <ip>, YIADDR <ip>, SIADDR <ip>, CHADDR <mac>, HOSTNAME "<str>", DNS_SERVER <ip>, ROUTER <ip>, SUBNET_MASK <ip>, LEASE_TIME <u32>.
• examples/l7/ntp/ — NTP (RFC 5905): LI <0..3>, VN <1..4>, MODE <1..7>, STRATUM <0..16>, POLL <u8>, PRECISION <i8>, REFID "<str>", TX_TIMESTAMP <u64>.
• examples/l7/ptp/ — PTP (IEEE 1588-2008): SYNC, DELAY_REQ, FOLLOW_UP, DELAY_RESP, ANNOUNCE, MSG_TYPE "<type>", VERSION <u8>, DOMAIN <u8>, SEQ_ID <u16>, CLOCK_ID "<eui64>".
• examples/l7/radius/ — RADIUS (RFC 2865 / RFC 2866): ACCESS_REQUEST, ACCESS_ACCEPT, ACCESS_REJECT, ACCESS_CHALLENGE, ACCOUNTING_REQUEST, ACCOUNTING_RESPONSE, CODE "<type>", ID <u8>, USER "<str>", NAS_IP <ip>, SERVICE_TYPE <u32>, FRAMED_IP <ip>.
• examples/l7/tacacs/ — TACACS (RFC 8907 TACACS+): AUTHEN, AUTHOR, ACCT, TYPE <AUTHEN|AUTHOR|ACCT>, SEQ <u8>, FLAGS <u8>, SESSION_ID <u32>, USER "<str>", PAYLOAD "<str>".
• examples/l7/syslog/ — SYSLOG (RFC 5424): FACILITY <0..23>, SEVERITY <0..7>, PRI <0..191>, HOSTNAME "<str>", APP "<str>", PROCID "<str>", MSGID "<str>", MSG "<text>", TRANSPORT TCP.
• examples/l7/netflow/ — NETFLOW (Cisco NetFlow v5): SRCIP <ip>, DSTIP <ip>, SRCPORT <u16>, DSTPORT <u16>, PROTO <u8>, PACKETS <u32>, OCTETS <u32>.
• examples/l7/ipfix/ — IPFIX (RFC 7011): DOMAIN_ID <u32>, SRCIP <ip>, DSTIP <ip>, SRCPORT <u16>, DSTPORT <u16>, PROTO <u8>, PACKETS <u32>, OCTETS <u32>.
• examples/l7/sflow/ — SFLOW (sFlow v5): AGENT_IP <ip>, SUB_AGENT_ID <u32>, SEQ <u32>, UPTIME <u32>, SAMPLES <u32>.

6. Layer 7 Web, Cloud-Native, Transport Security, VoIP & Remote Access Protocols (16 Protocols — docs/l7_web_and_cloud.md)

• examples/l7/http/ — HTTP (RFC 9112 HTTP/1.1): GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, METHOD "<verb>", URI "<path>", VERSION "<ver>", HOST_HDR "<host>", USER_AGENT "<str>", CONTENT_TYPE "<mime>", STATUS <u16>, REASON "<str>", HEADER "<k>" "<v>", BODY "<str>".
• examples/l7/http2/ — HTTP2 (RFC 9113): PREFACE, SETTINGS, HEADERS, DATA, WINDOW_UPDATE, PING, GOAWAY, STREAM_ID <u32>.
• examples/l7/grpc/ — GRPC (gRPC over HTTP/2): SERVICE "<str>", METHOD "<str>", GRPC_STATUS <u32>, PAYLOAD "<str>".
• examples/l7/websocket/ — WEBSOCKET (RFC 6455): OPCODE "<TEXT|BINARY|CLOSE|PING|PONG>" (or bare TEXT, BINARY, PING, PONG, CLOSE), FIN_BIT <0..1>, MASK_KEY <u32>, PAYLOAD "<str>".
• examples/l7/tls/ — TLS (RFC 8446 TLS 1.3): CLIENT_HELLO, SERVER_HELLO, CERTIFICATE, FINISHED, APP_DATA, ALERT, RECORD_VERSION <u16>, HANDSHAKE_VERSION <u16>, SNI "<str>", CIPHERSUITE <u16>, ALPN "<str>".
• examples/l7/quic/ — QUIC (RFC 9000): INITIAL, ZERO_RTT, HANDSHAKE, RETRY, SHORT, VERSION <u32>, DCID <u64>, SCID <u64>, TOKEN "<str>", PKT_NUM <u32>, PAYLOAD "<str>".
• examples/l7/tftp/ — TFTP (RFC 1350): RRQ, WRQ, DATA, ACK, ERROR, FILENAME "<str>", MODE "<str>", BLOCK <u16>, ERRCODE <u16>, ERRMSG "<str>".
• examples/l7/ftp/ — FTP (RFC 959): CMD "<str>", ARG "<str>", CODE <u16>, REPLY "<str>".
• examples/l7/ssh/ — SSH (RFC 4253): BANNER "<str>", KEXINIT, NEWKEYS, MSG_CODE <u8>, COOKIE "<str>", PAYLOAD "<str>".
• examples/l7/telnet/ — TELNET (RFC 854): WILL <u8>, WONT <u8>, DO <u8>, DONT <u8>, OPTION <u8>, DATA "<str>", PAYLOAD "<str>".
• examples/l7/whois/ — WHOIS (RFC 3912): QUERY, RESPONSE, DOMAIN "<str>", REGISTRAR "<str>".
• examples/l7/sip/ — SIP (RFC 3261): INVITE, BYE, CANCEL, METHOD "<verb>", URI "<str>", STATUS <u16>, REASON "<str>", FROM "<str>", TO "<str>", CALL_ID "<str>", CSEQ <u32>, VIA "<str>", CONTACT "<str>", CONTENT_TYPE "<str>", BODY "<sdp>", TRANSPORT TCP.
• examples/l7/rtp/ — RTP (RFC 3550): PT <u8>, SEQ <u16>, TIMESTAMP <u32>, SSRC <u32>, MARKER <0..1>, PAYLOAD "<str>".
• examples/l7/rtsp/ — RTSP (RFC 2326): OPTIONS, DESCRIBE, SETUP, PLAY, TEARDOWN, METHOD "<verb>", URI "<str>", STATUS <u16>, CSEQ <u32>, SESSION "<str>", TRANSPORT_HDR "<str>".
• examples/l7/stun/ — STUN (RFC 8489): BINDING_REQUEST, BINDING_RESPONSE, BINDING_ERROR, TXID <u32>, XOR_MAPPED_ADDR <ip>, SOFTWARE "<str>".
• examples/l7/ssdp/ — SSDP (UPnP Discovery): MSEARCH, NOTIFY, HOST_HDR "<str>", MAN "<str>", MX <u8>, ST "<str>", NT "<str>", NTS "<str>", USN "<str>", LOCATION "<str>".

7. Layer 7 Mail, Directory, Storage, Databases, Caches & Message Brokers (14 Protocols — docs/l7_mail_auth_storage_db.md)

• examples/l7/smtp/ — SMTP (RFC 5321): EHLO "<domain>", HELO "<domain>", MAIL_FROM, RCPT_TO, DATA, QUIT, CMD "<str>", PARAM "<addr>", CODE <u16>, REPLY "<str>", BODY "<str>".
• examples/l7/imap/ — IMAP (RFC 3501): TAG "<str>", CMD "<str>", ARG "<str>", STATUS "<str>", RESPONSE "<str>".
• examples/l7/pop3/ — POP3 (RFC 1939): CMD "<str>", ARG "<str>", OK, ERR, RESPONSE "<str>".
• examples/l7/kerberos/ — KERBEROS (RFC 4120): AS_REQ, AS_REP, TGS_REQ, TGS_REP, KRB_ERROR, REALM "<str>", CNAME "<str>", SNAME "<str>", ETYPE <i32>.
• examples/l7/ldap/ — LDAP (RFC 4511): BIND_REQ, BIND_RES, SEARCH_REQ, SEARCH_ENTRY, SEARCH_DONE, UNBIND_REQ, MSGID <i32>, BASE_DN "<str>", FILTER "<str>", RESULT_CODE <u32>.
• examples/l7/smb/ — SMB (MS-SMB2/3): COMMAND "<NEGOTIATE|SESSION_SETUP|TREE_CONNECT|CREATE|READ|WRITE|CLOSE|TREE_DISCONNECT|LOGOFF>", STATUS <u32>, SESSION_ID <u64>, TREE_ID <u32>, MSGID <u64>, SHARE "<str>", FILENAME "<str>".
• examples/l7/nfs/ — NFS (RFC 1813 / RFC 7530): VERS <u32>, PROC "<str>", TAG "<str>", PATH "<str>", XID <u32>.
• examples/l7/redis/ — REDIS (RESP Protocol): CMD "<str>", ARGS "<str>", REPLY_TYPE "<str>", VALUE "<str>".
• examples/l7/memcached/ — MEMCACHED: CMD "<str>", KEY "<str>", VALUE "<str>", FLAGS <u32>, EXPTIME <u32>, OPCODE <u8>, OPAQUE <u32>, CAS <u64>.
• examples/l7/mysql/ — MYSQL: GREETING, LOGIN, QUERY, OK, ERR, EOF, SERVER_VERSION "<str>", USER "<str>", DB "<str>", SQL "<query>", ERRCODE <u16>.
• examples/l7/postgres/ — POSTGRES (v3.0): STARTUP, QUERY, AUTH_OK, COMMAND_COMPLETE, READY_FOR_QUERY, ERROR_RESPONSE, USER "<str>", DB "<str>", SQL "<query>".
• examples/l7/mqtt/ — MQTT (v3.1.1 / v5.0): CONNECT, CONNACK, PUBLISH, PUBACK, SUBSCRIBE, SUBACK, PINGREQ, PINGRESP, DISCONNECT, CLIENT_ID "<str>", TOPIC "<str>", QOS <0..2>, RETAIN, PKT_ID <u16>, KEEPALIVE <u16>, RETURN_CODE <u8>.
• examples/l7/coap/ — COAP (RFC 7252): CON, NON, ACK, RST, CODE "<str>", MSGID <u16>, TOKEN <u32>, URI_PATH "<str>", CONTENT_FORMAT <u16>.
• examples/l7/amqp/ — AMQP (0-9-1 / 1.0): PROTOCOL_HEADER, CONNECTION_START, CHANNEL_OPEN, BASIC_PUBLISH, BASIC_DELIVER, HEARTBEAT, CHANNEL <u16>, EXCHANGE "<str>", ROUTING_KEY "<str>".

8. Layer 7 Industrial Control Systems (ICS) & SCADA/OT Protocols (6 Protocols — docs/l7_industrial_ot.md)

• examples/l7/modbus/ — MODBUS (Modbus TCP): FUNC "<name>" (or READ_COILS, READ_DISCRETE_INPUTS, READ_HOLDING_REGISTERS, READ_INPUT_REGISTERS, WRITE_SINGLE_COIL, WRITE_SINGLE_REGISTER, WRITE_MULTIPLE_REGISTERS), TXID <u16>, PROTO_ID <u16>, UNITID <u8>, ADDR <u16>, COUNT <u16>, VALUE <u16>, IS_RESPONSE.
• examples/l7/bacnet/ — BACNET (ASHRAE 135 BACnet/IP): WHO_IS, I_AM, READ_PROPERTY, WRITE_PROPERTY, INVOKE_ID <u8>, OBJECT_TYPE <u16>, OBJECT_INSTANCE <u32>, PROPERTY_ID <u32>, VALUE <u32>.
• examples/l7/dnp3/ — DNP3 (IEEE 1815): FUNC "<name>" (or CONFIRM, READ, WRITE, SELECT, OPERATE, DIRECT_OPERATE, UNSOLICITED_RESPONSE), SRC <u16>, DST <u16>, SEQ <u8>, GROUP <u8>, VARIATION <u8>, CRC <u16>.
• examples/l7/s7comm/ — S7COMM (Siemens S7 PLC): ROSCTR "<JOB|ACK|ACK_DATA|USERDATA>", FUNC "<SETUP_COMM|READ_VAR|WRITE_VAR|PLC_CONTROL>", PDU_REF <u16>, AREA <u8>, DB_NUM <u16>, OFFSET <u32>, COUNT <u16>.
• examples/l7/ethernetip/ — ETHERNETIP (ODVA EtherNet/IP & CIP): CMD "<name>" (or LIST_SERVICES, LIST_IDENTITY, LIST_INTERFACES, REGISTER_SESSION, UNREGISTER_SESSION, SEND_RR_DATA, SEND_UNIT_DATA), SESSION_HANDLE <u32>, STATUS <u32>, CONTEXT <u64>, CIP_SERVICE <u8>, CIP_CLASS <u16>, CIP_INSTANCE <u16>, CIP_ATTR <u16>.
• examples/l7/opcua/ — OPCUA (IEC 62541): MSG_TYPE "<HEL|ACK|ERR|OPN|CLO|MSG>", CHUNK_TYPE "<F|C|A>", SECURE_CHANNEL_ID <u32>, TOKEN_ID <u32>, SEQ_NUM <u32>, REQID <u32>, ENDPOINT_URL "<str>", NODE_ID "<str>".

FAQ: What is a .fasm file? (FrameAssembly vs. Flat Assembler vs. FPGA FASM)

What is a .fasm file in FrameAssembly?

A .fasm file is a plain-text network packet recipe defined by the FrameAssembly compiler (registered IANA vendor media type text/vnd.frameassembly, Freedesktop shared-mime-info subclass of text/plain). It allows network technicians, security engineers, and DevOps pipelines to write declarative "Packets as Code" specifications that compile into deterministic, nanosecond-precision .pcap and .pcapng packet captures without requiring root permissions, Python scripting, or raw sockets.

Why do other software tools also use the .fasm extension?

Historically, the .fasm extension has been used informally by two unrelated tools that lack registered IANA vendor media types:

1. Flat Assembler (FASM): An x86/x86-64 assembly compiler created by Tomasz Grysztar. Flat Assembler .fasm files contain CPU assembly instructions (mov, jmp, xor), directives (format PE, format ELF, section, use32), and ; comments, producing .exe or .o machine code.
2. FPGA FASM (FPGA Assembly): A plain-text hardware configuration format used by SymbiFlow / F4PGA / Project X-Ray. FPGA FASM files contain dot-separated FPGA tile feature paths (CLBLL_L_X12Y34.SLICEL_X0.ALUT.INIT[31:0] = 32'h00000000) and # comments, producing FPGA .bit bitstreams.

How does FrameAssembly disambiguate .fasm files?

FrameAssembly provides unambiguous, multi-layered disambiguation:

• IANA Media Type: Formally registered vendor tree media type text/vnd.frameassembly.
• Freedesktop XML MIME Database: Provides contrib/mime/text-vnd.frameassembly.xml with magic rules matching HOST, FLOW, and COMPILE blocks.
• Unix file(1) Magic: Magic rules in contrib/magic/frameassembly.magic identifying FrameAssembly network packet specifications.
• GitHub Linguist: Language definition in contrib/linguist/languages.yml and regex disambiguation in contrib/linguist/heuristics.yml.
• Editor Syntax Scope: Dedicated TextMate scope source.frameassembly in frameassembly-vscode (avoiding Flat Assembler's source.fasm).
• Compiler Error Diagnostics: Built-in detection in src/error.rs that automatically detects when an x86 Flat Assembler or FPGA FASM file is passed by mistake and guides the user with a plain-English explanation.

Documentation

Step-by-Step Guides & Practical Cookbooks

• Getting Started Guide — Step-by-step introduction for network technicians with zero programming background: anatomy of a .fasm file, colon/hyphen/Cisco dotted-quad MAC support, frameassembly show terminal preview, Wireshark/tcpdump-to-.fasm translation table, generating .fasm with ChatGPT/Claude/Copilot, and pairing frameassembly with Wireshark, tshark, and tcpreplay.
• Practical Use Cases & Recipes — Symptom-based quick-jump index and ready-to-copy .fasm recipes for simulating SNMPv1/v2c/v3 traps & polls, testing firewall rules and ACLs, verifying VLAN/QinQ trunks and DiffServ QoS, testing IDS/IPS & flow collectors, validating industrial OT dissectors, and sharing zero-noise captures.

Protocol & Topology Reference Guides

• Layer 2 Switching & Data-Link Protocols — ARP, VLAN (802.1Q), QINQ (802.1ad), LLDP, STP / RSTP, LACP, EAPOL (802.1X), and MPLS (8 protocols).
• Layer 3 Control, Tunneling, VPN & Routing Protocols — ICMP, NDP, IGMP, MLD, GRE, VXLAN, GENEVE, IPSEC, ESP, AH, IKEV2, WIREGUARD, OSPF, BGP, RIP, VRRP, HSRP, PIM, BFD, and OPENFLOW (20 protocols).
• Layer 4 Transport Protocols — TCP, UDP, and SCTP, including automatic 4-tuple SEQ/ACK and reply-port tracking, RFC 7323 TCP options, and SCTP multi-chunk signaling (3 protocols).
• Layer 7 SNMPv1, SNMPv2c & Encrypted SNMPv3 Guide — Network administrator's guide to SNMP1, SNMP2, and SNMP3 USM authentication (MD5/SHA/SHA256/SHA384/SHA512), encryption (DES/AES), and all 9 VARBIND data types (3 protocols).
• Layer 7 Infrastructure, Time, AAA & Flow Telemetry — DNS, MDNS, DHCP / DHCPv6, NTP, PTP, RADIUS, TACACS, SYSLOG, NETFLOW, IPFIX, and SFLOW (11 protocols).
• Layer 7 Web, Cloud-Native, Transport Security, VoIP & Remote Access — HTTP, HTTP2, GRPC, WEBSOCKET, TLS, QUIC, TFTP, FTP, SSH, TELNET, WHOIS, SIP, RTP, RTSP, STUN, and SSDP (16 protocols).
• Layer 7 Mail, Directory, Storage, Databases, Caches & Message Brokers — SMTP, IMAP, POP3, KERBEROS, LDAP, SMB, NFS, REDIS, MEMCACHED, MYSQL, POSTGRES, MQTT, COAP, and AMQP (14 protocols).
• Layer 7 Industrial Control Systems (ICS) & SCADA/OT — MODBUS, BACNET, DNP3, S7COMM, ETHERNETIP, and OPCUA (6 protocols).
• Multi-Protocol Network Topologies & Dual-Stack Scenarios — Multi-host enterprise, data center EVPN-VXLAN, campus 802.1X NAC, and industrial OT topologies (plus examples/ with 2,611 verified .fasm scenarios across all 81 protocols).

Standards Specifications, Developer & AI Architecture

• .fasm File Format & Media Type Specification (text/vnd.frameassembly) — Canonical RFC 6838 specification for the FrameAssembly .fasm file format: UTF-8 encoding rules, lexical magic numbers, disambiguation from x86 Flat Assembler and FPGA FASM files, security considerations, and links to IANA (contrib/iana/text-vnd.frameassembly.md), Freedesktop MIME (contrib/mime/text-vnd.frameassembly.xml), and GitHub Linguist (contrib/linguist/) registration artifacts.
• For Nerds: Architecture, Rust Library API & Formal Grammars — Six-stage Rust pipeline, embedding frameassembly as a Rust library (parse_program, compile_program, generate_pcap), formal grammars (grammar.ebnf, frameassembly.gbnf, frameassembly.lark), constrained LLM decoding, and examples/ SFT/RLVR corpus conventions.

License

This project is licensed under the MIT License. See LICENSE for details.