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.
- Every
.frasmscript needs only two blocks:host(who lives on the wire) andcompile(what they send). 1 packet line = 1 Ethernet framewith 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.
// 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"}# 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.frasm2. 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, andm(always lowercase, glued onto the number). - Use
wait 0nswhen you want back-to-back microbursts at the exact same nanosecond. waitalways rides on the end of a packet line — never alone on a blank line.- Export
.pcapngfor full nanosecond Wireshark precision, or classic.pcapfor microsecond tools liketcpdump,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.
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}"}hosthdr instead of hostTop-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:
| Rule | Write This | Not This |
|---|---|---|
| File extension | .frasm (text/vnd.frameassembly) | .fasm (that is x86 Flat Assembler) |
| Built-in keywords | Lowercase [a-z0-9]+ only: echorequest, innervlan, sackperm, clienthello | Underscores or caps: echo_request, inner_vlan, SYN |
| Host IP literals | Plain 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 '...' |