Threat model

What first-bite protects, where untrusted input enters, what the design does about it, and what it does not do. Status words: built (the code exists and runs), designed (decided, not implemented), not built (nothing exists).

Assets

AssetWhere it isWho should reach it
Decoded records: every captured UDP and TCP packet in full, with its decoded fieldsthe ZeroMQ PUB socket; /var/log/first-bite/mind.log at log level info; files written by --output and the local-file sink; the configured sinksthe operator and the systems the operator configured
Storage credentials: the Azure account key, the S3 access key id and secretthe service environment (/etc/first-bite/first-bite.env) or systemd credential files; in process memorythe service process and root
The capture privilege: CAP_NET_RAW and CAP_NET_ADMIN on the tapped interfacesthe mind processnothing that enters through a packet, a dictionary or a socket
The dictionary: the message definitions of the tapped system/etc/first-bite/dictionarythe operator; it can be as sensitive as the document it transcribes

Trust boundaries and what is done at each

BoundaryTrustWhat the design doesStatus
The tapped network to mindhostile: any host on the link chooses the bytes of every frameFrames are parsed by etherparse and the decoder in safe Rust; first-party code has no unsafe. A malformed frame is counted and dropped. A field beyond the payload decodes to null. Decoding one packet costs at most the fields of one message (4,096). Random and truncated payloads are decoded in bite/tests/robustness.rsbuilt
With two or more interfaces, frames wait in a queue bounded at 65,536 frames and 256 MiB; a frame that does not fit is dropped and countedbuilt
The process holds only the two capture capabilities, as an unprivileged user, under the systemd sandbox in deployment/first-bite.service (NoNewPrivileges, ProtectSystem=strict, restricted address families, no devices)built
Packet content reaches the log only as JSON, and the logger writes control characters as escapes, so a packet cannot forge a log linebuilt
Dictionary files to the decodersupplied by the operator, possibly received from someone else; in the browser, any file a visitor is handedLimits in bite/src/limits.rs: 4 MiB per file, 10,000 files, 4,096 fields per message, 65,536 entries per values object, fields within the first 65,535 bytes of a payload, JSON nesting of 128. Anything over a limit is reported and left out. bite/tests/hostile_dictionary.rs loads adversarial and damaged dictionariesbuilt
A dictionary is data: it names bit ranges and labels. Nothing in it is executed, and no name in it becomes a file path. In an object name a topic cannot leave its prefixbuilt
The decoder page builds the document with text nodes only, reads at most 4 MiB per file and 10,000 files, and draws at most 1,024 bytes of a payload. Files are read in the page and sent nowherebuilt
Dictionary signing: a way to check who wrote a dictionary before loading itnot built
The ZeroMQ PUB socket to its readersplaintext and unauthenticated: the socket cannot check who connects, so who reads it is decided by where its owner binds itThe built-in publisher binds 127.0.0.1. A publisher bound to an address other machines can reach logs a warning at startup. The container example publishes the port on the host's loopback onlybuilt
Under a security block (transport.md) a publisher bound to an address that is not loopback stops startup unless allow_plaintext_bind: true is set, and a subscriber that reads the feed from another host stops startup. Consumers on other hosts are served by the Zenoh sink or an HTTPS sinkbuilt
Authentication or encryption on the socket (ZeroMQ CURVE)not built
A publisher socket to a subscriberthe subscriber trusts the configured address to be a first-bite publisherMessages over 16 MiB are refused by the socket. A record that is not JSON is not forwarded to the REST sink. The topic is sanitised before it is used in an object name or a Zenoh keybuilt
Record signing: a way for a reader to check that a record came from a given capture point and was not alterednot built
mind to a sink (REST, Azure Blob Storage, S3, Zenoh)the endpoint is configured by the operator; the network between is not trustedTLS certificates are verified for https:// endpoints and there is no setting to turn that off. The REST and Azure clients follow no redirect. An answer is read up to 1 MiB and quoted up to 512 characters. With no security block an http:// endpoint is allowed and sends records in clear: the operator's choicebuilt
A security block states the level every sink is held to before anything connects: loopback-plaintext, tls or mtls, a minimum TLS version, a key-exchange policy (classical, or the hybrid group X25519MLKEM768 preferred or required) and whether the FIPS module is required. A sink that cannot meet it stops startup. All TLS uses one crypto provider (rustls with aws-lc-rs). mind security show prints what each path will usebuilt
Credentials are not in configuration files: a key holds a ${NAME} reference resolved from the service environment, or a _file path. A credential is never logged or quoted in an error: its type prints ***, and the S3 sink removes both keys from a store's answer. /etc/first-bite is 0750 root:firstbite, files 0640built
Zenoh endpoints, mode and TLS identity come from a standard Zenoh configuration file. With no security block it is passed through unread; under one, its endpoints, scouting and client certificate are checked against the levelbuilt
The hostroot and the firstbite user are trusted; other local users are notRecord files are created 0640; the log directory and the working directory are 0750; the environment file is 0640 root:firstbite. install.sh sets these on every runbuilt
The --mock UDP socketdevelopment only: every datagram becomes a recordBinds 127.0.0.1 unless another address is givenbuilt
Contributors to the repositorya pull request is untrusted until reviewedThe controls in SECURITY.md: leak gate, pin check, advisory audit, dependency policy, CodeQL, Scorecard, Dependabot. Commits on main are signedbuilt

What the design does not do

Not doneConsequenceStatus
Encryption or authentication on the ZeroMQ socketsA socket bound beyond loopback puts every record on that network in clear with no check of who connects, and a subscriber cannot tell a first-bite publisher from another process at the configured address. Keep publishers on loopback, which a security block enforces, and serve other hosts through the Zenoh or HTTPS sinksnot built
Dictionary signingThe decoder loads whatever is in the dictionary directory. A changed dictionary changes what records say; it cannot run code or exceed the limits above. Protect the directory with file permissions (install.sh makes it writable by root only)not built
Record signingA consumer of the socket, a file or a bucket cannot verify where a record came from or that it is unalterednot built
Encryption of records at restThe log, --output files and local-file sink are plain JSON, protected by file permissions onlynot built
Rate limiting of the tapped trafficA flood on the tapped link is processed as fast as the host allows; frames beyond that are dropped by the kernel or the queue and counted in the lognot built
Keeping a credential out of process memory or the service environmentA process running as firstbite or root can read the credentials. systemd credential files (LoadCredential=) keep them out of the environment filebuilt as described

The source of this page is a Markdown file in the repository.