FrameAssembly (frameassembly)

Quickstart • Why FrameAssembly? • Syntax Guide • All 81 Protocols (Defaults) • Sub-Keyword Reference • Documentation

FrameAssembly (frameassembly v1.2.2) builds standard .pcap and .pcapng packet capture files from readable plain-text descriptions (.fasm) across 81 network protocols spanning Layers 2 through 7.

You define the hosts in your scenario and list the frames exchanged between them using familiar networking terms—IPs, MACs, VLAN tags, TCP flags, routing attributes, or application fields. FrameAssembly handles the binary packet framing, byte lengths, checksums, and TCP sequence tracking automatically, producing a clean .pcap file ready to inspect in Wireshark / tshark or send onto a network interface with tcpreplay.

Why FrameAssembly?

Tools like Wireshark and tcpdump record traffic that already exists on a network, and tcpreplay transmits existing .pcap files over a network interface—but neither helps when the packet capture you need doesn't exist yet.

Building custom .pcap files from scratch usually forces an awkward trade-off:

• Writing Python scripts (Scapy) and manually managing TCP sequence numbers, return ports, and nested protocol objects in code.
• Editing raw hex dumps (text2pcap) where changing a single field breaks byte offsets, header lengths, and checksums.
• Building a physical or virtual lab just to capture a specific protocol handshake, error condition, or alert—while filtering out background LAN chatter.

FrameAssembly gives you direct, bit-level control over packet headers through a readable text format that looks like a network diagram:

• Test firewalls, ACLs, and IDS/IPS sensors: Craft exact TCP flag combinations, blocked-port probes, fragmented IPv4 packets, or double-tagged VLAN/QinQ frames and replay them against an appliance with tcpreplay.
• Verify monitoring, SIEM, and flow collectors: Generate valid SNMPv1/v2c/v3 traps, Syslog alerts, or NetFlow/IPFIX/sFlow exports without waiting for real hardware faults.
• Simulate routing, overlays, VoIP, and OT/SCADA traffic: Build BGP, OSPF, VXLAN, IPsec, WireGuard, TLS 1.3, SIP/RTP, or industrial PLC captures (Modbus, S7comm, DNP3, OPC UA) without physical lab equipment.
• Share reproducible, zero-noise captures: Check a 15-line .fasm text file into Git or attach it to a ticket instead of passing around noisy binary .pcap dumps.

Quickstart

1. Install frameassembly

Cross-Platform Installer (Linux, macOS & BSDs): Checks for required build tools, sets up the Rust toolchain if missing, installs frameassembly from Crates.io, and installs the VS Code .fasm syntax extension if code is on PATH:

curl -fsSL [https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/install.sh](https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/install.sh) | sh

Or install directly via Cargo (Rust >= 1.85):

cargo install frameassembly

2. Write a Traffic Specification (demo.fasm)

Every protocol works out of the box with standard RFC defaults—you only write the fields you want to customize:

// Define the endpoints
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 }

// List the packets exchanged between them (1 line = 1 frame)
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
}

// Build the capture
compile {
    web_session(client, server)
}

3. Compile to .pcap, Inspect & Replay

$ frameassembly demo.fasm -o output.pcap
Successfully parsed 2 hosts, 1 flows
Starting PCAP compilation...
Successfully generated output.pcap

$ tshark -r output.pcap
    1 0.000000000    10.0.0.10 → 10.0.0.80    TCP 58 51234 → 80 [SYN] Seq=0 Win=65535 Len=0 MSS=1460
    2 0.001000000    10.0.0.80 → 10.0.0.10    TCP 58 80 → 51234 [SYN, ACK] Seq=0 Ack=1 Win=65535 Len=0 MSS=1460
    3 0.002000000    10.0.0.10 → 10.0.0.80    TCP 54 51234 → 80 [ACK] Seq=1 Ack=1 Win=65535 Len=0
    4 0.003000000    10.0.0.10 → 10.0.0.80    HTTP 97 GET /index.html HTTP/1.1
    5 0.008000000    10.0.0.80 → 10.0.0.10    HTTP 126 HTTP/1.1 200 OK  (text/html)

Once verified in Wireshark or tshark, you can transmit the .pcap over a live network interface with tcpreplay:

sudo tcpreplay -i eth0 output.pcap

What FrameAssembly handled behind the scenes:

• Return Port Swapping: 51234 -> 80 on c -> s automatically reversed to 80 -> 51234 on c <- s without retyping port numbers.
• Automatic TCP SEQ & ACK Progression: The http request and response automatically reused the established TCP session, emitted PSH, ACK segments, and incremented Seq and Ack counters by exact payload byte lengths.
• Checksums & Nanosecond Timing: Ethernet headers, IPv4/TCP checksums, HTTP Content-Length, and wait timestamp offsets (0.001s, 0.002s, 0.003s, 0.008s) were calculated automatically.

Syntax Guide

1. host, flow & compile Blocks

FrameAssembly syntax is completely case-insensitive across all keywords, protocol names, modifiers, time units (ns, us, ms, s, m), and identifiers (host or HOST, tcp or TCP). Single-line comments start with //.

• host <name> { ip <address> [mac <mac>] }: Binds a symbolic name to an IPv4 or IPv6 address. If mac is omitted, a deterministic unicast MAC—or RFC 1112 (01:00:5e:...) / RFC 2464 (33:33:...) multicast MAC for multicast IPs—is derived automatically.
• flow <name>(<param1>, <param2>, ...) { ... }: Defines a reusable sequence of packets:
  • A -> B: A is the sender (source), B is the receiver (destination).
  • A <- B: B is the sender (source), A is the receiver (destination).
• compile { ... }: Generates packets by passing concrete hosts into your flows. Because flows don't hardcode IPv4 vs. IPv6, the same flow can be run with IPv4 hosts and IPv6 hosts, and repeated inside loop <count> { ... }:

host client_v4  { ip 192.168.1.50 }
host server_v4  { ip 192.168.1.100 mac 00:11:22:33:44:55 }
host client_v6  { ip 2001:db8::10 }
host server_v6  { ip 2001:db8::100 }
host mdns_mcast { ip 224.0.0.251 }

flow tcp_handshake(client, server) {
    client -> server tcp syn srcport 50100 dstport 443 win 65535
    client <- server tcp syn ack win 65535 wait 1ms
    client -> server tcp ack wait 1ms
}

flow mdns_probe(node, mcast) {
    node -> mcast mdns query qname "_http._tcp.local" qtype "PTR" wait 2ms
}

compile {
    loop 2 {
        tcp_handshake(client_v4, server_v4)
        tcp_handshake(client_v6, server_v6)
    }
    mdns_probe(client_v4, mdns_mcast)
}

2. Universal Layer 2–4 Modifiers

Any packet statement can include Layer 2, Layer 3, Layer 4, payload, and timing modifiers—allowing you to wrap upper-layer protocols inside VLAN trunks, QinQ service tags, MPLS label stacks, QoS markings, or fragmented IPv4 packets:

3. Combining Cross-Layer Encapsulation & Application Protocols

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 }

// TLS 1.3 handshake carried over QinQ (2000/150) + MPLS (Label 40960) + DSCP EF (46)
flow metro_backhaul_tls(cpe, hq) {
    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_backhaul_tls(branch_cpe, hq_gateway)
}

4. CLI & Editor Options

# Default output is output.pcap, or specify a path with -o / --output
frameassembly demo.fasm -o output.pcap

# Install only the VS Code .vsix syntax highlighting extension without cloning:
curl -fsSLo /tmp/frameassembly.vsix [https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/frameassembly-vscode/frameassembly-vscode-1.2.2.vsix](https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/frameassembly-vscode/frameassembly-vscode-1.2.2.vsix) && code --install-extension /tmp/frameassembly.vsix && rm -f /tmp/frameassembly.vsix

Supported Protocols & Default Wire Behavior

Every protocol can be used with zero mandatory sub-keywords, emitting RFC-compliant default wire headers when optional fields are omitted: