onyks-os/networksandboxengineA deterministic network sandbox for testing nftables rules. It uses ephemeral Linux network namespaces (netns) and Scapy to validate firewall logic safely.
Why NSE? • Oracle contract • Wire assertions • Features • Requirements • Installation • Quickstart • How It Works • Project Structure
Testing firewall rulesets on a live Linux system poses significant risks: malformed rules can drop SSH management sessions, leak cleartext traffic during testing, or leave orphan firewall tables active on the host.
Network Sandbox Engine (NSE) provides a safe, reproducible testing harness. It constructs ephemeral Linux network namespaces, wires virtual ethernet pairs, compiles nftables rulesets, and injects synthetic Layer 2 and Layer 3 packets using Scapy. All evaluation happens inside the sandbox namespace: host firewall state is never altered.
Key architectural properties:
nse_<uuid>) and are completely removed during teardown.nse/ is ~1200 statements at 98% test coverage.NSE creates network namespaces, loads nftables rulesets and reads kernel trace events, so it runs as root. It does not open a socket, a port or an RPC endpoint of any kind — it is a library and a CLI that you invoke, and it holds privileges only for the duration of a run.
Version 2.1.0 removed the FastAPI/Svelte web interface that earlier releases
shipped. That interface ran in-process as root from 2.0.0 onward, which was a
large attack surface for a testing tool; the code remains in the git history at
tag v2.0.0 if you need it.
A firewall test is a negative assertion — "this packet did not get through" — and a negative assertion is worth nothing unless the instrument is known to be working. A trace monitor that never attached to the kernel and a firewall that blocked everything produce byte-identical output.
NSE therefore refuses to report a verdict it cannot show it measured:
| Guarantee | Mechanism |
|---|---|
| The monitor was attached before the first test packet | A readiness canary is injected and re-injected until its kernel trace is observed. No observation, no run. |
| The monitor was still attached after the last one | A liveness canary runs after injection. If it is missed, the verdict stream is declared truncated. |
| The parser understood what the kernel said | Trace lines that no pattern matches are counted, and any count above zero is an error rather than a debug log. |
| The monitor did not die quietly | The read loop records why it ended — clean stop, unexpected EOF, timeout or crash — and only a clean stop is acceptable. |
| A missing verdict is not a pass | The CLI runner fails when the number of observed verdicts differs from the number expected, in either direction. |
Canary packets are excluded from results by trace id, so they never appear in your verdict stream.
The suite proves this holds, rather than asserting it: make test-blind forces
the parser to understand nothing, and the build fails unless the runner exits
non-zero. That job runs in CI on every push.
nft monitor trace reports what the ruleset decided. It cannot report what
left an interface the ruleset never matched on, which is the question a
zero-leak claim actually asks. PCAPAsserter covers that: an AsyncSniffer
wrapper that captures on a named interface and hands the frames back, so a test
can assert that a stimulus produced none.
from nse import PCAPAsserter
asserter = PCAPAsserter(iface="veth-host")
await asserter.start()
# ... send the stimulus ...
leaked = await asserter.stop()
assert not leaked, leaked
The same rule as the trace oracle applies, and it is the caller's to enforce: a sniffer that never attached and a firewall that blocked everything both return an empty list. Capture the stimulus once with the ruleset flushed and require the frame to be seen before asserting its absence.
The default filter suppresses link-local noise, and nothing else.
DEFAULT_FILTER excludes ARP and ICMPv6 types 133-137 - Neighbour Discovery,
which carries a hop limit of 255 and cannot reach a remote observer. Everything
else is captured, including ICMPv6 echo to a globally routable address. A
filter argument is combined with that default; replace_default_filter=True
uses yours alone. The escape hatch exists because the filter is compiled into
BPF and evaluated in the kernel: a packet it excludes never reaches userspace,
so no consumer can recover it downstream. Until 2.1.2 the default read not arp and not icmp6, which discarded routable ICMPv6 as well - see
issue #14.