Try in Browser • Quick Download • Use Cases • How It Works • Comparison • 81 Protocols & Docs
At first you may think FrameAssembly is a programming language for systems development, but ironically it is a tool built specifically for the very people who hate programming -> Networking & Cybersecurity professionals.
Have you ever wished you could just describe traffic in a few lines of simple networking keywords, get your own .pcap, and do a little SQL injection onto your favourite coworker's machine with the help of tcpreplay?
Well, here you have it and it's fun and free to use (even commercially) -> as long as I'm not responsible for what you do with it :)
Compilation works in both directions -> Compile FrameAssembly .frasm code into .pcap or .pcapng captures across 81 protocols, or reverse captured .pcap / .pcapng traces back
into .frasm code for anonymizing, editing, inspecting, and replaying with tcpreplay, Wireshark / tshark, or Suricata / Zeek.
A complete TCP handshake plus an HTTP request, in a few lines:
host client { ip 10.0.0.10 mac 00:11:22:33:44:55 }
host firewall { ip 10.0.0.1 mac aa:bb:cc:dd:ee:ff }
compile {
client -> firewall tcp syn srcport 51234 dstport 80 win 65535 mss 1460 wait 1ms
client <- firewall tcp syn ack win 65535 mss 1460 wait 1ms
client -> firewall tcp ack wait 1ms
client -> firewall http get uri "/healthz" hosthdr "api.example.com" wait 2ms
client <- firewall http status 200 reason "OK" body "ok"
}
$ frameassembly show test.frasm
# Time (ms) Source -> Destination Proto Bytes Summary
--------------------------------------------------------------------------------------------------------------
1 0.000 10.0.0.10 -> 10.0.0.1 TCP 58 51234 -> 80 [SYN] seq=1000 len=0
2 1.000 10.0.0.1 -> 10.0.0.10 TCP 58 80 -> 51234 [SYN ACK] seq=1000 ack=1001 len=0
3 2.000 10.0.0.10 -> 10.0.0.1 TCP 54 51234 -> 80 [ACK] seq=1001 ack=1001 len=0
4 3.000 10.0.0.10 -> 10.0.0.1 HTTP 102 51234 -> 80 [ACK PSH] seq=1001 ack=1001 len=48
5 5.000 10.0.0.1 -> 10.0.0.10 HTTP 94 80 -> 51234 [ACK PSH] seq=1001 ack=1049 len=40
$ frameassembly test.frasm && sudo tcpreplay -i eth0 test.pcap
$ frameassembly reverse test.pcap edited.frasmPick the fastest route. Every option runs offline and writes standard .pcap (classic libpcap) or .pcapng (PCAPNG with nanosecond timestamps) files.
-
Recommended CLI Install (
Cargo, Crates.io):cargo install frameassembly
-
Browser Playground — nothing to install: frameassembly.ai.studio
-
Windows (PowerShell, no Administrator rights):
irm https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/install.ps1 | iex
-
macOS & Linux (installs binary + shell Tab completion):
curl -fsSL https://raw.githubusercontent.com/SteveWinschel/FrameAssembly/main/install.sh | sh -
VS Code Extension — syntax highlighting, live inline error checking, and 1-click typo Quick Fix:
code --install-extension SteveWinschel.frameassembly-vscode
-
Offline Archives &
.debPackages from GitHub Releases (each.zip/.tar.gzincludesframeassembly, offlinedocs/, and starterexamples/; on Windows you can also drag a.frasmor.pcapfile directly ontoframeassembly.exein Explorer):System Download Windows (x64) frameassembly-windows-x64.zipmacOS (Apple Silicon) frameassembly-macos-arm64.tar.gzLinux (x64) frameassembly-linux-x64.tar.gzDebian / Ubuntu frameassembly_amd64.debOther builds (Windows ARM64, macOS Intel, Linux ARM64,
.debfor ARM64) andSHA256SUMS.txtare on the same page. -
Homebrew & Scoop:
# Homebrew (macOS & Linux) brew install SteveWinschel/tap-FrameAssembly/frameassembly # Scoop (Windows) scoop bucket add frameassembly https://github.com/SteveWinschel/homebrew-tap-FrameAssembly && scoop install frameassembly
Rust Library & WebAssembly (`docs.rs`, `npm`)
# Browser and Node.js WebAssembly package
npm install frameassembly-wasmRust 1.88+ library API reference: docs.rs/frameassembly • Compiler internals: docs/13_for_nerds.md
First capture in one minute:
cat <<'EOF' > demo.frasm
host client { ip 10.0.0.10 }
host server { ip 10.0.0.20 }
compile {
client -> server icmp echorequest id 1 seq 1 payload "hello" wait 2ms
client <- server icmp echoreply id 1 seq 1 payload "hello"
}
EOF
frameassembly show demo.frasm # packet ladder in the terminal
frameassembly demo.frasm # writes classic libpcap demo.pcap (double-click in Wireshark)
frameassembly demo.frasm demo.pcapng # writes nanosecond PCAPNG demo.pcapng
frameassembly reverse demo.pcap # writes demo.frasm from any .pcap or .pcapngTesting whether Checkmk Event Console, Zabbix, PRTG, LibreNMS, SolarWinds, or snmptrapd actually pages on an encrypted SNMPv3 authPriv trap usually means configuring
a switch agent, loading vendor MIBs, matching EngineIDs, and pulling a fiber patch cord out of hardware. With FrameAssembly, you generate encrypted SNMPv3 traps (SHA-256 + AES-128),
SNMPv1/v2c notifications, Syslog events, and NetFlow / IPFIX / sFlow records in seconds:
host core_sw { ip 10.10.1.2 mac 00:1a:2b:3c:4d:01 }
host checkmk { ip 10.10.1.50 mac 00:1a:2b:3c:4d:50 }
compile {
core_sw -> checkmk 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
core_sw -> checkmk vlan 100 syslog facility 16 severity 3 hostname "core-sw-01" app "link" msg "Gi0/1 changed state to down"
}
$ frameassembly snmp_alert.frasm snmp_alert.pcap && sudo tcpreplay -i eth0 snmp_alert.pcapProving that your NDR sensor, DNS sinkhole, or SIEM catches Shadow IT SaaS/AI uploads (unauthorized TLS sni or HTTP/3 quic), rogue dhcp servers, or unauthorized mdns / ssdp
discovery normally means hunting down noisy third-party .pcap captures. FrameAssembly builds exact detection-test captures in a few lines of .frasm code:
host workstation { ip 10.40.5.25 mac 00:50:56:40:05:25 }
host rogue_iot { ip 10.40.5.99 mac 00:50:56:40:05:99 }
host sec_gateway { ip 10.40.5.1 mac 00:1c:73:40:05:01 }
host mdns_group { ip 224.0.0.251 }
flow shadow_it_and_ndr_audit(ws, iot, gw, mcast) {
ws -> gw dns query txid 0x4401 qname "shadow-ai-upload.example.net" qtype "a" wait 1ms
ws <- gw dns response txid 0x4401 qname "shadow-ai-upload.example.net" qtype "a" rcode 5 wait 2ms
ws -> gw tcp syn srcport 53443 dstport 443 win 65535 mss 1460 wait 1ms
ws <- gw tcp syn ack win 65535 mss 1460 wait 1ms
ws -> gw tcp ack wait 1ms
ws -> gw tls clienthello sni "shadow-ai-upload.example.net" ciphersuite 4866 alpn "h2" wait 2ms
ws <- gw tls alert payload "BLOCKED_BY_SNI_POLICY" wait 2ms
ws -> gw quic initial version 1 dcid "a1b2c3d4" scid "e5f60708" pktnum 1 payload "QUIC_SHADOW_SAAS" wait 2ms
iot -> mcast mdns query qname "_airplay._tcp.local" qtype "ptr" wait 2ms
iot -> gw ssdp msearch st "ssdp:all"
}
compile { shadow_it_and_ndr_audit(workstation, rogue_iot, sec_gateway, mdns_group) }
$ frameassembly ids_test.frasm ids_test.pcap && suricata -r ids_test.pcap -k noneSending a single spoofed packet at a stateful firewall (nftables / iptables, Palo Alto, FortiGate, CheckPoint) won't test your application rules because the firewall drops
mid-stream data without a completed 3-way TCP handshake. FrameAssembly tracks TCP SEQ/ACK numbers and swaps reply ports on <- automatically, so you can verify DMZ rules, 802.1Q vlan
tags, and industrial OT (modbus, dnp3, s7comm, opcua) policies before a maintenance window:
host eng_ws { ip 192.168.20.25 mac 00:11:22:33:44:55 }
host dmz_srv { ip 203.0.113.10 mac aa:bb:cc:dd:ee:ff }
host ot_plc { ip 192.168.110.50 mac 00:0e:8c:aa:bb:01 }
flow acl_audit(c, srv, plc) {
c -> srv vlan 20 tcp syn srcport 52000 dstport 443 win 65535 mss 1460 wait 1ms
c <- srv vlan 20 tcp syn ack win 65535 mss 1460 wait 1ms
c -> srv vlan 20 tcp ack wait 1ms
c -> srv vlan 20 tls clienthello sni "portal.example.com" ciphersuite 4866 alpn "h2" wait 2ms
c -> srv vlan 20 tcp syn srcport 52001 dstport 22 win 64240 wait 1ms
c <- srv vlan 20 tcp rst ack wait 1ms
c -> plc vlan 110 tcp syn srcport 52002 dstport 502 win 64240 mss 1460 wait 1ms
c <- plc vlan 110 tcp syn ack win 64240 mss 1460 wait 1ms
c -> plc vlan 110 tcp ack wait 1ms
c -> plc vlan 110 modbus readholdingregisters txid 1 unitid 1 addr 0 count 2
}
compile { acl_audit(eng_ws, dmz_srv, ot_plc) }
# Replay into a SPAN/TAP sensor port (for inline firewalls, split client/server NICs via tcpprep + tcpreplay -i eth0 -I eth1)
$ frameassembly acl_test.frasm acl_test.pcap && sudo tcpreplay -i eth0 acl_test.pcapWhen you need to attach a production capture to a vendor TAC ticket without leaking internal subnets or customer hostnames—or turn a live tcpdump capture into a Git-tracked regression
test—run frameassembly reverse. Swap the host IPs, MACs, VLAN tags, or TLS sni names in .frasm code, delete background chatter, and recompile—FrameAssembly recalculates all L3/L4
checksums and TCP SEQ/ACK numbers automatically:
$ frameassembly reverse customer_incident.pcap sanitized_ticket.frasmhost host1 { ip 192.0.2.10 mac 00:11:22:33:44:01 }
host host2 { ip 198.51.100.20 mac 00:11:22:33:44:02 }
compile {
host1 -> host2 vlan 100 tcp syn srcport 54321 dstport 443 win 64240 mss 1460 wait 1ms
host1 <- host2 vlan 100 tcp syn ack win 64240 mss 1460 wait 1ms
host1 -> host2 vlan 100 tcp ack wait 1ms
host1 -> host2 vlan 100 tls clienthello sni "sanitized-app.example.com" ciphersuite 4865 alpn "h2" wait 2ms
host1 <- host2 vlan 100 tcp rst ack
}
$ frameassembly sanitized_ticket.frasm sanitized_ticket.pcapMost .frasm files need only host declarations and a compile { ... } block (add an optional flow block when reusing sequences across host pairs). Built-in keywords are lowercase with
zero underscores or hyphens (host, flow, compile, echorequest, clienthello):
host— Declare Endpoints Once: Bind names toip(IPv4 or IPv6) and optionalmacaddresses (omitted unicast MACs default to00:00:00:00:00:01,:02, ... in declaration order), or declare MAC-only switches (host sw1 { mac 00:1c:73:00:00:01 }) for Layer 2 switching protocols (lldp,stp,lacp,eapol,vlan,qinq,mpls,arp).compile— Emit Standard Captures: Write packet statements directly insidecompile { ... }using->and<-arrows, optionalvlan/qinq/mplsheaders, Layer 2–7 protocol keywords, and post-packetwaitgaps (ns,us,ms,s,m;10msdefault between packets when omitted).flow(Optional) — Reuse Packet Exchanges: Group a multi-step sequence intoflow name(a, b) { ... }and call it insidecompileacross IPv4 or IPv6 host pairs.
host sw1 { mac 00:1c:73:00:00:01 }
host sw2 { mac 00:1c:73:00:00:02 }
compile {
sw1 -> sw2 lldp chassisid "00:1c:73:00:00:01" portid "Ethernet1/1" ttl 120 sysname "leaf-01" wait 2ms
sw1 <- sw2 stp rstp rootid "4096/00:1c:73:00:00:02" bridgeid "4096/00:1c:73:00:00:02" portid 0x8001 cost 0 flags 0x3c
}
Under the hood, the compiler handles the packet plumbing automatically:
- Stateful TCP Tracking: Advances
SEQandACKnumbers from payload byte lengths andSYN/FINflags, while flipping ports, IPs, and MAC addresses on<-replies. - Wire-Valid Framing & Checksums: Computes Ethernet/802.1Q/802.1ad framing, IPv4/IPv6 lengths, and L3/L4/L7 checksums out of the box.
- PCAP-to-
.frasmDecompilation: Turns existing.pcapand.pcapngcaptures into.frasmcode so you can anonymize IPs or edit headers and recompile. Encrypted payloads (such as SNMPv3authPriv, TLS application data, SSH, or IPsecESP) stay intact astcporudpstatements withpayload/hexpayloadso recompiled captures preserve exact wire bytes. - Git-Friendly: Turns binary
.pcapblobs into.frasmcode files that you can review withgit diffin CI/CD and regression suites.
| Capability | FrameAssembly (.frasm) |
Scapy (Python) | Full Lab VMs / GNS3 | Downloaded .pcap |
|---|---|---|---|---|
| Setup Overhead | Single CLI binary, Browser Playground, or VS Code | Python + venv + packages |
Hypervisor + OS images | None |
| Admin Rights to Build PCAP | Never required | Not for offline wrpcap |
Admin / hypervisor access | Not required |
TCP SEQ/ACK Math |
Automatic on -> / <- |
Manual state in Python | Real OS TCP stack | Fixed static stream |
Anonymize & Edit .pcaps |
frameassembly reverse (.pcap <-> .frasm) |
Custom Python parsing & checksum scripts | Cannot import .pcap into live state |
Hex editor / tcprewrite only |
| Version Control | L2–L7 .frasm code |
Imperative scripts | Multi-GB disk images | Binary blobs |
| Capture Hygiene | Zero background chatter | Isolated, high boilerplate | ARP / mDNS / OS noise | Foreign IPs & noise |
FrameAssembly is built to work alongside tcpreplay, Wireshark / tshark, Suricata, and Zeek—not replace them. Instead of maintaining Python environments or booting
multi-VM labs just to synthesize 10 packets—or struggling to sanitize a customer capture—you compile or reverse .frasm code in milliseconds and feed the resulting .pcap straight into your
existing replay and analysis tools.
Install the VS Code extension (SteveWinschel.frameassembly-vscode) for .frasm syntax highlighting, live inline error checking powered by the bundled WebAssembly compiler, and 1-click Quick
Fixes when muscle memory types sport instead of srcport or ECHO_REQUEST instead of echorequest.
# Inspect packet timing, flags, sequence numbers, and byte lengths in the terminal
frameassembly show demo.frasm
# Compile .frasm code (.pcap writes classic libpcap; .pcapng writes nanosecond PCAPNG)
frameassembly demo.frasm
frameassembly demo.frasm custom.pcapng
# Decompile an existing .pcap or .pcapng into .frasm code (writes trace.frasm by default)
frameassembly reverse trace.pcap
frameassembly reverse trace.pcap sanitized.frasm
# Print CLI version and command help
frameassembly version
frameassembly helpFrameAssembly natively compiles and decompiles 81 protocols across Layers 2–7. Start at the Docs Index (pick your role, or search all 81 protocols by name) or use the guides below:
- Docs Index (
docs/README.md) — Role-based starting points and a searchable table of all 81 protocols with one-line examples. - Scenario Index (
examples/README.md) — Curated.frasmscenarios for SNMPv3 monitoring, firewalls and VLANs, IDS and Shadow IT, routing and EVPN, and OT/SCADA. - Getting Started (
docs/01_getting_started.md) — Minimalhost+compilesyntax, reusableflowblocks, AI copy-paste prompt, reverse PCAP conversion, and your first capture. - Real-World Use Cases (
docs/02_use_cases.md) — Copy-paste recipes for Checkmk/Zabbix SNMPv3 traps, Shadow IT & NDR detection, firewall/VLAN verification, and PCAP anonymization. - Topologies & Dual-Stack (
docs/11_topologies_and_dual_stack.md) — Multi-hop gateways, VLAN/QinQ trunks, and IPv4/IPv6 dual-stack flows. .frasmMedia Type Specification (docs/12_frasm_specification.md) — Formaltext/vnd.frameassemblyformat rules and how.frasmdiffers from the unrelated.fasmformats.- Compiler Architecture (
docs/13_for_nerds.md) — Lexing, parsing, semantic validation, and binary emission internals for curious engineers.
- Layer 2 — Switching & Data Link (
docs/03_l2_protocols.md) — Ethernet II, IEEE 802.1Qvlan, 802.1adqinq,arp,stp/rstp,lldp,lacp,mpls, andeapol(802.1X). - Layer 3 — Network, Routing & Tunnels (
docs/04_l3_protocols.md) —IPv4,IPv6,icmp,ndp,igmp,mld,gre,ipsec(esp/ah),ikev2,vxlan,geneve,ospf,bgp,rip,pim,vrrp,hsrp,bfd,openflow, andwireguard. - Layer 4 — Transports (
docs/05_l4_transports.md) — Statefultcp(flags, window,mss, options, automaticSEQ/ACK),udp, andsctp. - Layer 7 — SNMPv1 / v2c / v3 (
docs/06_l7_snmp.md) —get,getnext,getbulk,set,response,trap,inform,report, and encryptedsnmp3USM (SHA-256auth +AES-128priv). - Layer 7 — Infrastructure & Telemetry (
docs/07_l7_infra_and_telemetry.md) —dns,mdns,dhcp/DHCPv6,ntp,ptp,radius,tacacs,syslog,netflow,ipfix, andsflow. - Layer 7 — Web, Cloud, Security & VoIP (
docs/08_l7_web_and_cloud.md) —http,http2,grpc,websocket,tls(clienthello,sni,alpn,alert),quic,ssh,telnet,ftp,tftp,whois,sip,rtp,rtsp,stun, andssdp. - Layer 7 — Mail, Auth, Storage, Databases & Brokers (
docs/09_l7_mail_auth_storage_db.md) —smtp,imap,pop3,kerberos,ldap,smb,nfs,postgres,mysql,redis,memcached,mqtt,coap, andamqp. - Layer 7 — Industrial OT & ICS (
docs/10_l7_industrial_ot.md) —modbus,dnp3,s7comm,opcua,bacnet, andethernetip.
Released under the MIT License. Free for personal, academic, and commercial use.