first-bite: the first bite of every byte, before it reaches its addressee

Open source, Apache-2.0

Binary messages off the wire, decoded, for those you authorise

first-bite listens on a tap or a mirror port, local or tunnelled (ERSPAN/GRE), decodes fixed-layout binary messages against a dictionary, and publishes each one as a record of typed values for the consumers its owner allows. It never transmits on the capture interface, and one core handles 450,000 packets per second.

Interactive decoder Read the documentation Technical brief (PDF)

Two native systems exchange binary messages on a link. A tap or a switch mirror port sends a copy of every frame one way to first-bite, which captures it, decodes it against a dictionary of JSON files and publishes one record of typed values per message, as JSON or CBOR, on a ZeroMQ PUB socket. Object storage, an HTTP endpoint, a Zenoh data fabric, a Cursor-on-Target transform and a subscriber of the owner's own read the records. Nothing is sent back to the link, so the native systems are not delayed, blocked or altered.

Measured on one core

AMD Ryzen 7 8845HS, release build of the 1.1.0 code, 2026-11-15, the machine also running other work. The command behind each figure.

It listens, and takes nothing from the link

first-bite opens the capture interface for reading and never sends on it. On a passive tap there is no path from the monitor ports back to the link, so nothing first-bite does can delay, block or alter the traffic between the native systems, and if it stops, the link is unaffected.

Where a tap cannot be fitted, a switch mirror port gives the same copy: forwarding is not affected, but the switch does the copying and drops mirrored frames first when it is busy. A remote mirror sends the copy in an ERSPAN, GRE or VXLAN tunnel to first-bite on another host, which unwraps it; that adds the mirrored traffic to the network carrying the tunnel. It was built to open up the traffic of a tactical local network that until then was visible only to the systems exchanging it.

Four ways to give first-bite a copy of a link. A breakout tap has one monitor port per direction, so first-bite uses two capture interfaces; the link is not affected and nothing is lost at the tap; built and measured. An aggregating tap merges both directions into one port, with the same effect and loss; built and measured. A switch mirror port (SPAN) does not affect forwarding, carries both directions on one port, and the switch drops mirrored frames first when it is busy; built. A remote mirror sends each frame in a GRE, ERSPAN or VXLAN tunnel across a routed network to first-bite on any host the session can route to, which unwraps it; it behaves as a mirror port, adds the tunnel's traffic to that network and can also lose what the path drops; built, not yet run against a switch.
Four ways to take the copy, with the status of each. Running on a tap or a mirror port covers interface preparation and the loss counters.

The message set is data, not code

A dictionary is a directory of JSON files that gives the bit range, type and value labels of every field. The same binary decodes a weather station's UDP reports, the frames on a vehicle CAN bus or a message set of your own, and bite check validates a dictionary and runs the test vectors it carries.

The 23 bytes of a weather-station Observation message, 0200174b583700fb2e18bcda9b4236000004030201beef, with the bit range of each of its nine fields marked. A table gives the dictionary entry for each field (start bit, stop bit, type, options) and the value it decodes to: message_type Observation, message_length 23, station_id KX7, temperature -12.34, pressure 101325, wind_direction 271.5, humidity 45.5, sample_serial 16909060, checksum beef.
The weather-station Observation test vector, field by field. Paste your own bytes into the interactive decoder, or read the dictionary format.

One core is far more than a link needs

The whole pipeline (read a frame, parse Ethernet, IP and UDP, decode, build the record, publish) takes 2.2 µs per packet. A link carrying 1,000 messages per second therefore uses about 0.2% of one core, and a record is on the bus about two microseconds after its frame is read.

The project's first decoder managed 194 messages per second. Its rewrite decoded 1,700,000 on the same recorded messages, and also decodes the fields the first returned as null.

Three measurements on one core. Decoder throughput on a logarithmic scale: the project's first decoder managed 194 messages per second and the rewritten one 1,700,000 on the same recorded messages. Time per packet on a linear scale: 2.2 microseconds for the whole pipeline, of which decoding is 0.47. Share of one core by message rate, computed from 2.2 microseconds per packet: 0.2 percent at 1,000 messages per second, 2.2 percent at 10,000 and 22 percent at 100,000.
Every figure comes from a command in the repository: performance.

One decode, as many consumers as you allow

Without a tap, each consumer of a binary interface writes its own parser and holds its own connection to the native system. With first-bite the decode happens once: consumers on the host subscribe to a ZeroMQ socket and read records, as JSON or CBOR, or read what a sink wrote to S3-compatible storage, Azure Blob, an HTTP endpoint, a Zenoh data fabric or a file. A transform emits Cursor-on-Target. The owner decides who reads: the record socket binds loopback by default, no sink runs unless it is configured, and HTTPS and storage endpoints are reached over TLS with the certificate checked.

Left, point to point: each of four consumers implements the binary interface and holds its own connection to native system A, so there are four parsers and four connections for A to serve. Right, with a tap: first-bite decodes once and publishes, the four consumers subscribe and read records, and there is one decoder and no connection to A or B.

Where it runs, and what it reads

One process, mind, from one archive per platform with nothing to install on the target. The standard Linux build (glibc 2.31 or later) and the fully static one are built and run on x86-64; the 64-bit Arm Linux, macOS and Windows archives are built in CI; not run locally. The same decoder reads CAN-style frames; a SocketCAN capture source is designed, not built.

Where first-bite runs. The standard Linux build needs glibc 2.31 or later and is built and run on x86-64 in Ubuntu 20.04, 22.04, 24.04 and 26.04. The self-contained Linux build is fully static, needs only a Linux kernel 3.2 or later, and is built and run on x86-64. Archives for 64-bit Arm Linux, macOS and Windows are built in CI and not run locally. The container image replays a capture file, measured. The decoder library is compile-checked for iOS, Android, Windows, WebAssembly and 64-bit Arm Linux; no application is built. A build with no internet access uses vendored dependencies.
Deployment covers which archive to choose, the service, the container and building without internet access.
A table of link types against decoding and capture. IP networks: decoding is built and measured at 2.1 million messages per second, and capture is built for an interface, a capture file and a UDP socket. CAN bus: decoding is built and measured at 1.8 million frames per second with the same decoder, and a SocketCAN capture source is designed, not built. MIL-STD-1553 and ARINC 429 sources are not built, and neither is importing a DBC file as a dictionary.

Try it in five minutes

Needs a Rust toolchain, a C/C++ compiler, CMake and the libpcap headers.

git clone https://github.com/USAREUR-AF/first-bite && cd first-bite
make build

# Validate a dictionary and run its test vectors.
cargo run -p bite -- check dictionaries/weather-station

# Decode one payload by hand.
cargo run -p bite -- decode dictionaries/weather-station --port 40100 \
    0200174b583700fb2e18bcda9b4236000004030201beef

# Replay a capture file through the whole pipeline.
cargo run -p mind -- --pcap-file examples/weather-station.pcap \
    --dictionary dictionaries/weather-station --output

To decode traffic your own network already carries, capture the Network Time Protocol with the ntp dictionary: sudo ./target/debug/mind eth0 --dictionary dictionaries/ntp --filter "udp port 123".

Documentation

ArchitectureThe crates, the path from frame to record, sinks and transforms.The recordThe published record: its fields, its two versions, JSON and CBOR.Cursor-on-Target to a TAK serverDecode a message, make a Cursor-on-Target event, deliver it to a TAK server.Dictionary formatEvery key of a dictionary and everything bite check reports.PerformanceThe measured figures and the command behind each.Tap or mirror portTaps, mirror ports and tunnelled mirrors; capture interfaces; loss counters.DeploymentWhich archive for which machine, the service, the container, offline builds.Zenoh data fabricWhere records go on a goat data fabric.Related projectsfirst-bite beside Open Billie and octo-pod.What a goat data fabric requires of a publishergoat support in first-bite is optional and off by default: it is the cargo feature goat, and nothing here applies to a build without it.Joining a goatnetgoat support is optional and off by default: it is the cargo feature goat, and a mind built without it behaves exactly as one that never heard of...Reading an ICDAn interface document answers six questions for each interface, and it rarely answers them in one place.ConventionsTwo people who transcribe the same document should produce the same dictionary, byte for byte.Transcription workflowTranscription is a loop: enter a message's fields as the document prints them, build the dictionary from the tables, run the gates, fix what they...Vectors and validationA vector is a payload and the values it must decode to. It is the only gate that tests what a field means: the right bits, the right scale, the...Maintaining a dictionaryA new revision of the document arrives. The work is to transcribe what changed, see exactly what that does to consumers of the decoded records,...Worked example: the glasshouse controllerA complete transcription, start to finish, of a synthetic interface document: GZC-ICD-001, for an invented glasshouse zone controller.Document issues: GZC-ICD-001Every place the document is wrong or can be read two ways, and what the glasshouse dictionary does about it.GZC-ICD-001 Revision B: Glasshouse Zone Controller GZC-4 Supervisory LinkInterface control document. This document is synthetic. The GZC-4 does not exist; the document was written for the first-bite worked example in...GZC-ICD-001 Revision C: Glasshouse Zone Controller GZC-4 Supervisory LinkInterface control document. This document is synthetic. The GZC-4 does not exist; the document was written for the first-bite worked example in...From an interface document to a dictionaryAn interface control document (ICD) defines the messages two systems exchange, usually as hundreds of pages of word-and-bit tables.ChecklistsThree lists to print: one for the person transcribing, one for the person reviewing, one for the release.Security assessment, November 2026Scope: the tree at commit ff35ab3 and the commits that follow it on the security branch.OpenSSF Best Practices badge: the answersThe OpenSSF Best Practices badge is a questionnaire a maintainer answers about the project.OpenSSF Scorecard, check by checkOpenSSF Scorecard scores a repository from 0 to 10 on each of eighteen checks and publishes a weighted average.Threat modelWhat first-bite protects, where untrusted input enters, what the design does about it, and what it does not do.Transport securityOne security block in the configuration states how records may leave the host.