Reference R37 min readFrameAssembly v3.1.2
llms-full.txt

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 frameassembly or in JS/TS via npm install frameassembly-wasm.
  • Ships formal grammar/frasm.{ebnf,gbnf,lark} schemas + /llms-full.txt tested 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:

StageWhat 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 EncoderSerializes 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 <-> reverseEmits 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-wasm
In-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
Open in Playground
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 } ;