Guide 014 min readFrameAssembly v3.1.2
llms-full.txt

Your First .pcap in 60 Seconds (host + compile)

Name two boxes, draw -> and <- arrows, and spit out a Wireshark-ready .pcap or .pcapng with zero Scapy imports and zero sudo.

TL;DR — What Matters Here
  • Every .frasm script needs only two blocks: host (who lives on the wire) and compile (what they send).
  • 1 packet line = 1 Ethernet frame with MACs, IP/TCP/UDP lengths, and RFC checksums calculated for you.
  • Zero sudo, zero Npcap drivers, and zero virtualenvs — runs locally in your browser tab or via one static CLI binary.

1. host + compile: Name Boxes, Draw Arrows

If you can read a firewall rule or a tcpdump line, you already know .frasm. Every capture needs just two pieces: one or more host blocks declaring endpoints, and one compile block listing the frames flying between them.

Put plain IPv4 or IPv6 addresses inside each host block (no /24 masks). Skip mac whenever you don’t care about specific vendor OUIs, and the compiler hands out deterministic MACs in order (00:00:00:00:00:01, 00:00:00:00:00:02, ...) so your Wireshark conversations stay tidy.

first_dns_check.frasm9 lines
Open in Playground
// 1. Name the boxes on your network (zero /24 subnet math)
host laptop-of-hope { ip 192.168.10.25 }
host corp-resolver { ip 192.168.10.53 }
// 2. Draw -> and <- top-to-bottom (1 line = 1 Ethernet frame)
compile {
laptop-of-hope -> corp-resolver dns query txid 0x1a2b qname "intranet.corp.local" qtype "A" wait 3ms
laptop-of-hope <- corp-resolver dns response txid 0x1a2b qname "intranet.corp.local" qtype "A" rdata "10.20.30.40"
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# Compile straight to first_dns_check.pcap
frameassembly first_dns_check.frasm

# Or eyeball the relative timestamps and byte lengths in your terminal first
frameassembly show first_dns_check.frasm

2. Keep Columns Straight (->, <-, and wait)

Spot the <- on line 2 above? Keeping laptop-of-hope pinned on the left and corp-resolver pinned on the right makes a 20-packet exchange read like an RFC whiteboard sketch: laptop-of-hope -> corp-resolver fires left-to-right, while laptop-of-hope <- corp-resolver fires the reply right-to-left and swaps MACs, IPs, and ports automatically.

Packet #1 always lands at 0.000000000 s. Tacking wait <number><ns|us|ms|s|m> onto the end of a line sets the clock gap *before* the next packet arrives (default 10ms when omitted).

  • Time units: ns, us, ms, s, and m (always lowercase, glued onto the number).
  • Use wait 0ns when you want back-to-back microbursts at the exact same nanosecond.
  • wait always rides on the end of a packet line — never alone on a blank line.
  • Export .pcapng for full nanosecond Wireshark precision, or classic .pcap for microsecond tools like tcpdump, tcpreplay, Suricata, and Zeek.

3. Let the Compiler Babysit TCP seq & acknum

Hand-crafting TCP in Scapy usually ends with Wireshark painting your screen black-and-red over bad sequence numbers or broken pseudo-header checksums. FrameAssembly tracks every 4-tuple session (client:port <-> server:port) across raw tcp and all TCP-based Layer 7 protocols (http, tls, ssh, smb, postgres, bgp, modbus, ...).

Set srcport and dstport once on the opening syn, and every <- reply and L7 payload inherits the port pair, swaps direction when needed, and advances seq / acknum by exact payload byte count.

http_healthcheck.frasm13 lines
Open in Playground
host probe { ip 10.20.1.50 }
host web_srv { ip 10.20.1.80 }
compile {
// 3-way TCP handshake on port 80
probe -> web_srv tcp syn srcport 51820 dstport 80 win 65535 mss 1460 wait 1ms
probe <- web_srv tcp syn ack win 65535 mss 1460 wait 1ms
probe -> web_srv tcp ack wait 1ms
// HTTP GET <-> 200 OK reuse 51820 <-> 80 and advance TCP seq automatically
probe -> web_srv http get uri "/healthz" hosthdr "web.corp.local" wait 2ms
probe <- web_srv http status 200 reason "OK" contenttype "application/json" body "{\"healthy\":true}"
}
Why HTTP uses hosthdr instead of host

Top-level host already declares network boxes, so HTTP and SSDP use hosthdr "web.corp.local" to set the Host: header without parser drama.

4. Four Rules That Save You Every Time

All 81 protocols obey the exact same lexical rules, with zero guessing whether some random option wants snake_case, camelCase, or hyphens:

RuleWrite ThisNot This
File extension.frasm (text/vnd.frameassembly).fasm (that is x86 Flat Assembler)
Built-in keywordsLowercase [a-z0-9]+ only: echorequest, innervlan, sackperm, clienthelloUnderscores or caps: echo_request, inner_vlan, SYN
Host IP literalsPlain host IP: host fw { ip 10.0.0.1 }CIDR masks or =: ip = "10.0.0.1/24"
Comments & quotes// comments and double quotes "..."# / ; comments or single quotes '...'