Network Stack Test Suite

A modular test suite for validating a custom L3/L4 network stack (the Device Under Test, DUT) over real Ethernet — RFC conformance and known-vulnerability classes for IP, UDP, ICMP, and TCP, driven by Scapy and pytest, with both a CLI and a PySide6/pyqtgraph GUI.

The suite is built to produce a developer-oriented report (HTML/PDF) that leads with the failures, the RFC clause each one violates, and what the DUT actually did — so it can be handed to whoever fixes the stack.

netstack-gui mid-run: DUT configuration up top, the test picker and per-test description on the left, live tx/rx plot on the right, and the run summary with report export along the bottom.

Highlights

• CLI and GUI, both driving the same subprocess-based orchestration layer (src/runner.py) — never diverging in how a run is invoked.
• Runs against a Linux- or Windows-based DUT, selected explicitly (--target-stack), independent of whichever OS the suite itself runs on. See docs/architecture.md.
• Client or server role (--role) — the suite can initiate (validating the DUT's responder) or respond while the DUT initiates (validating the DUT's client path).
• Proxy-DUT testing — run two instances (client + backend) to validate a relaying DUT's server and client legs end-to-end: transparent, HTTP CONNECT (RFC 9110/9112) or SOCKS5 (RFC 1928). --proxy-leg {front,back} additionally aims the whole existing IP/ICMP/UDP/TCP suite at either of the proxy's own stacks, inducing traffic through the front so the back leg has something to observe.
• Per-test catalog — every test carries a description, RFC clause, and roles, surfaced in the GUI and the report appendix.
• Addressable DUT target — interface, target IP/MAC, target stack, and optional ports (--dut-port / --dut-source-port, or the GUI's DUT configuration form): leave the destination port unset and one random ephemeral port is chosen for the whole session; set it and every port-specific test uses exactly that.
• Custom/raw L7 payloads — zeros, ones, random, or user-supplied text/hex/file — usable by the automated suite and via an ad-hoc Custom Packet sender.
• Passive pcap recorder (netstack-cli record) and an opt-in tshark-style debug log (run --debug) for wire-level forensics.
• Real-time plotting of traffic during a run (GUI), plus a developer-oriented PDF/HTML report with a findings section, artifacts/repro, and appendices (full test catalog + RFC index).
• Self-validated: tests_internal/ proves the framework's own packet crafting, interface, plotting, reporting, CLI, and GUI work — before any of it touches a DUT.

Download

Standalone builds (no Python needed on the target) are on the Releases page:

Windows — NetstackTestSuite-windows-x64.exe

1. Download it from the latest release.
2. Double-click — it self-elevates via UAC (raw sockets need Administrator).
3. Install Npcap if you haven't (the driver can't be bundled).

Linux — NetstackTestSuite-linux-x86_64

1. Download it, then chmod +x NetstackTestSuite-linux-x86_64.
2. Raw sockets need privilege: run with sudo, or once grant the capability with sudo setcap cap_net_raw,cap_net_admin+eip ./NetstackTestSuite-linux-x86_64.
3. Needs a desktop session plus the Qt libs libegl1 libgl1 libxkbcommon0 libdbus-1-3.

See packaging/README.md. Both are built by the Release workflow on a version-tag push.

Quickstart (from source)

pip install -e ".[gui,dev]"
pytest tests_internal/                                    # validate the framework itself first

netstack-cli run --iface eth0 --dut-ip 10.0.0.5 --target-stack linux
netstack-gui

See docs/getting_started.md for platform-specific privilege setup (Npcap on Windows, setcap on Linux).

Build the standalone executable

python -m PyInstaller NetstackTestSuite.spec --noconfirm

Output: dist/NetstackTestSuite.exe — a single UAC-elevating file that doubles as its own pytest worker. Details in packaging/.

Repository layout

src/                  Core framework
  packet_engine/      Packet crafting, L2 I/O, capture, preflight, server responder
  target_profiles/    Linux/Windows behavioral baselines
  reporting/          Result models + developer PDF/HTML reports
  plotting/           Live plot + static charts
  custom_packet/      Ad-hoc craft & send
  proxy/              Proxy-DUT testing: echo backend, CONNECT/SOCKS5, relay client
  cli/  gui/          netstack-cli and netstack-gui front ends
  utils/              Privileges, safety gate, debug log, paths
  catalog.py          Per-test metadata (description, RFC, roles)
  runner.py           Subprocess-based run orchestration
tests/                DUT-facing suite: ip/ udp/ icmp/ tcp/{syn,state_machine,congestion}/ proxy/
tests_internal/       Framework self-validation — no DUT required
docs/                 Architecture, setup, RFC coverage matrix
packaging/            PyInstaller spec entry, build script, Inno Setup installer
reports/              Generated per-run artifacts (gitignored)

Every package has its own README.md documenting each module and its public API.

Framework (src/)

Start at src/README.md — the module map. Per-package docs: packet_engine · target_profiles · reporting · plotting · custom_packet · proxy · utils · cli · gui

Test suites

• tests/README.md — the DUT-facing suite (per-module + per-test docs)
• tests_internal/README.md — framework self-validation

What the output looks like

The report is the artifact you hand to whoever fixes the stack — findings first, each naming its RFC clause, what the test checked, and what the DUT actually did:

Documentation

• docs/architecture.md — design decisions and why
• docs/getting_started.md — install and privilege setup
• docs/rfc_coverage.md — RFC clause → test file matrix
• docs/screenshots.md — every UI element, in one place
• docs/proxy_testing.md — testing a proxy DUT with two instances

Development

• main — stable; each release is tagged from here.
• development — ongoing work; branch features off it and merge back.

Commits follow Conventional Commits (type(scope): description). Run the self-tests before pushing:

pytest tests_internal/

License

Licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). The distributed binaries bundle Scapy, PySide6/Qt, and other dependencies under their own licenses.