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? • 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 ~1150 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:
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.
run_test_pipeline) returning structured Pydantic models (TestRequest, TraceEvent).nse_<id>) wired directly to the host.nse_router_<id>) and Server (nse_server_<id>) chain for forwarding and NAT testing.nse-runner). Exits non-zero on a wrong verdict and on a verdict it failed to observe.mypy --strict), architectural boundary enforcement (import-linter), ruff formatting, and a coverage ratchet (, floor 98%).nft)ip)ip netns and kernel trace operations)On Debian or Ubuntu systems:
sudo apt update && sudo apt install -y nftables iproute2 conntrack
Install the core engine with CLI support:
pip install "network-sandbox-engine[cli]"
For local development:
git clone https://github.com/onyks-os/NetworkSandboxEngine.git
cd NetworkSandboxEngine
make setup
import asyncio
from nse.core.netns_controller import NetnsController
from nse.core.pipeline import run_test_pipeline
from nse.models.test_request import TestRequest, PacketSpec
rules = """
table ip filter {
chain input {
type filter hook input priority 0; policy drop;
tcp dport 80 accept
}
}
"""
request = TestRequest(
rules=rules,
packets=[
PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=80),
PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=22),
],
)
async def main():
controller = NetnsController()
events = await run_test_pipeline(request=request, controller=controller)
for evt in events:
if evt.verdict:
print(f"[{evt.chain}] Verdict: {evt.verdict}")
asyncio.run(main())
Create a test file firewall_test.yaml:
tests:
- name: "Allow HTTP Port 80, Drop SSH Port 22"
topology: simple
rules: |
table ip filter {
chain input {
type filter hook input priority 0; policy drop;
tcp dport 80 accept
}
}
packets:
- protocol: tcp
src_ip: 10.0.0.1
dst_ip: 10.0.0.2
dst_port: 80
expected_verdict: ACCEPT
- protocol: tcp
src_ip: 10.0.0.1
dst_ip: 10.0.0.2
dst_port: 22
expected_verdict: DROP
expected_verdict is per packet. Unknown keys are rejected rather than
defaulted, so a typo fails the suite instead of quietly becoming an expectation
you never wrote.
Run the suite with root privileges:
sudo nse-runner --file firewall_test.yaml
Exit codes: 0 all packets matched; 1 a verdict was wrong or the engine
could not observe one. Oracle errors are reported separately from firewall
failures, because they mean the measurement broke, not the ruleset.
podman build -t nse .
podman run --rm --cap-add=NET_ADMIN --cap-add=NET_RAW \
-v "$PWD/firewall_test.yaml:/suite.yaml:ro" nse --file /suite.yaml
Useful for pinning the nftables version your rules are tested against.
NSE orchestrates Linux kernel network subsystems and trace interfaces through a structured multi-stage execution pipeline:
graph TD
subgraph Step1["1. Test Specification"]
Req["<b>TestRequest</b><br/>ruleset + packets + topology"]
end
subgraph Step2["2. Ephemeral Netns Sandbox"]
direction TB
Netns["<b>Netns Setup</b><br/>nse_<id> & veth links"]
RuleEng["<b>Rule Engine</b><br/>validate & load nftables"]
Inject["<b>Scapy Injector</b><br/>L2/L3 packet injection"]
NFT["<b>Kernel nftables</b><br/>meta nftrace set 1"]
Netns --> RuleEng
RuleEng --> Inject
Inject --> NFT
end
subgraph Step3["3. Trace Evaluation & Oracle"]
direction TB
Harvester["<b>Trace Harvester</b><br/>nft monitor trace stream"]
Oracle["<b>Deterministic Oracle</b><br/>TraceEvents & verdicts"]
Harvester --> Oracle
end
Step1 --> Step2
Step2 --> Step3RuleEngine.validate() dry-runs the ruleset using nft --check -f.NetnsController creates the isolated network namespace and configures virtual ethernet (veth) interfaces.meta nftrace set 1).ScapyInjector injects synthetic frames across the veth link.TraceHarvester captures nft monitor trace events and returns structured TraceEvent objects.For complete technical specifications, see the Technical Architecture Guide.
NetworkSandboxEngine/
├── nse/ # Core PyPI package (network-sandbox-engine)
│ ├── core/ # Kernel primitives, pipeline, and naming rules
│ ├── models/ # Pydantic models (TestRequest, PacketSpec, TraceEvent)
│ └── cli/ # Headless YAML runner entrypoint
├── docs/ # Architecture specs and MkDocs web documentation
├── tests/ # Unit, golden file, and privileged e2e tests
│ └── fixtures/nft_trace/ # Golden `nft monitor trace` corpus
├── pyproject.toml # Build backend configuration
└── Makefile # Local automation and CI workflow
One tag. git push origin vX.Y.Z builds, signs with Sigstore, publishes the
GitHub Release, uploads to TestPyPI, installs from TestPyPI and smoke-tests it,
and only then uploads to PyPI. Rehearse with make release-dry.
See docs/RELEASING.md.
Full interactive web documentation is available at:
https://onyks-os.github.io/nse/
Build the documentation locally:
make docs
Serve the documentation with hot-reload on http://127.0.0.1:8000:
make docs-serve
Run static linting and unit tests:
make verify
Run full local CI verification (includes linting, unit tests, frontend build, docs build, PyPI smoke test, and privileged integration tests):
make ci-local
This project is licensed under the MIT License.
| 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. |
make test-cov