Reference R37 min readFrameAssembly v3.1.2
Under the Hood: Rust Crate, frameassembly-wasm & EBNF Grammars
For the folks who actually *do* like programming: how the 6-stage Rust pipeline works and how to embed .frasm <-> .pcap in Cargo or Node/browser tests.
TL;DR — What Matters Here
- Same zero-socket Rust engine everywhere: CLI binary, VS Code Packet Studio LSP, and this browser Playground (
frameassembly-wasm). - Embed in Rust CI tests via
cargo add frameassemblyor in JS/TS vianpm install frameassembly-wasm. - Ships formal
grammar/frasm.{ebnf,gbnf,lark}schemas +/llms-full.txttested against 2,600+ packet scenarios.
1. Six Stages: .frasm <-> Wire Bytes
Everything runs in safe Rust in memory — zero shelling out, zero libpcap C bindings, zero raw sockets:
| Stage | What It Actually Does |
|---|---|
1. Lexer (lexer::lex) | Tokenizes UTF-8 .frasm, -> / <- arrows, time units, IPv4/IPv6, colon/hyphen/Cisco MACs, hex strings, and OIDs with UTF-16 spans. |
2. Parser (parser::parse_program) | Builds the AST (host, flow, compile) and runs Levenshtein typo suggestions (Did you mean ...?) against protocol vocabularies. |
3. Semantic Validator (validate_semantics) | Enforces L2 MAC-only vs L3–L7 IP rules, igmp/ndp/mld families, the 9-protocol transport whitelist, and field bounds. |
4. Stateful Expander (compile_program) | Inlines flow(...) calls, advances the nanosecond wait clock (0ns start, +10ms default), and tracks 4-tuple TCP seq/acknum + port memory. |
| 5. Wire Encoder | Serializes L7 payloads (including SNMPv3 USM key localization + AES-128-CFB and DNP3 CRC-16 chunks), wraps L4/L3/MPLS/QinQ/802.1Q/Ethernet II, and computes RFC checksums. |
6. .pcap / .pcapng <-> reverse | Emits classic .pcap (0xa1b2c3d4) or nanosecond .pcapng (IfTsResol=9), and decompiles binary captures back into host1, host2, ... .frasm. |
2. Embedding in Rust (cargo) or Node / Browser (npm)
Writing automated Suricata/Zeek regression tests or building your own browser packet tool? Generate .pcap bytes directly in RAM without touching disk:
Terminal Commands (FrameAssembly CLI v3.1.2)
# Rust crate (crates.io)
cargo add frameassembly
# Browser & Node.js WebAssembly package (npm)
npm install frameassembly-wasmIn-Memory Rust Test (src/main.rs) (rust)
use frameassembly::{
compile_frasm_str_to_pcap_bytes,
compile_frasm_str_to_pcapng_bytes,
reverse_pcap_bytes_to_frasm,
};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let src = r#"
host sensor { ip 10.0.0.10 }
host target { ip 10.0.0.20 }
compile {
sensor -> target icmp echorequest id 1 seq 1 wait 2ms
sensor <- target icmp echoreply id 1 seq 1
}
"#;
let pcap_bytes = compile_frasm_str_to_pcap_bytes(src)?;
let pcapng_bytes = compile_frasm_str_to_pcapng_bytes(src)?;
let roundtrip_frasm = reverse_pcap_bytes_to_frasm(&pcapng_bytes)?;
assert!(pcap_bytes.len() > 24 && roundtrip_frasm.contains("echorequest"));
Ok(())
}Export (frameassembly / frameassembly-wasm) | Returns |
|---|---|
compile_frasm_str_to_pcap_bytes(src) / compile_frasm_to_pcap(src) | Classic libpcap .pcap bytes (byte vector in Rust, Uint8Array in JS/TS). |
compile_frasm_str_to_pcapng_bytes(src) / compile_frasm_to_pcapng(src) | Nanosecond .pcapng bytes (byte vector in Rust, Uint8Array in JS/TS). |
reverse_pcap_bytes_to_frasm(bytes) / reverse_pcap(bytes) | Auto-detects .pcap vs .pcapng and decompiles into canonical .frasm source. |
validate_frasm(src) & inspect_frasm(src) | Structured line/column diagnostics + relative-timestamp packet summaries. |
3. Constrained Decoding Schemas (EBNF, GBNF, Lark)
Running local llama.cpp constrained decoding or feeding an LLM? Grab grammar/frasm.ebnf, grammar/frasm.gbnf, grammar/frasm.lark from the GitHub repo (or /llms-full.txt from this site):
grammar_verified_sample.frasm7 lines
host verifier_a { ip 2001:db8:10::1 mac 00:1b:21:aa:00:01 }host verifier_b { ip 2001:db8:10::2 mac 00:1c:73:bb:00:02 }compile { verifier_a -> verifier_b ndp neighborsolicit target 2001:db8:10::2 slla 00:1b:21:aa:00:01 wait 1ms verifier_a <- verifier_b ndp neighboradvert target 2001:db8:10::2 tlla 00:1c:73:bb:00:02}Excerpt from grammar/frasm.ebnf (v3.1.2) (ebnf)
program = { host_block | flow_block } , compile_block , { host_block | flow_block } ;
host_block = "host" , identifier , "{" , host_attr , { host_attr } , "}" ;
host_attr = ( "ip" , ip_literal ) | ( "mac" , mac_literal ) ;
flow_block = "flow" , identifier , "(" , param_list , ")" , "{" , { frame_stmt } , "}" ;
compile_block = "compile" , "{" , { frame_stmt | flow_call } , "}" ;
frame_stmt = identifier , ( "->" | "<-" ) , identifier , protocol_kw , { modifier } ;Related protocol references:ndp (IPv6 NDP)icmp (ICMP / ICMPv6)dns (DNS (UDP/TCP))bgp (BGP-4 / 4-Byte ASN)