network-sandbox-engine 2.1.1__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/PKG-INFO +126 -17
  2. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/README.md +124 -16
  3. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/PKG-INFO +126 -17
  4. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/SOURCES.txt +28 -0
  5. network_sandbox_engine-2.2.0/nse/__init__.py +42 -0
  6. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/cli/runner.py +253 -79
  7. network_sandbox_engine-2.2.0/nse/core/async_work.py +39 -0
  8. network_sandbox_engine-2.2.0/nse/core/environment.py +66 -0
  9. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/mock_listener.py +80 -1
  10. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/naming.py +8 -2
  11. network_sandbox_engine-2.2.0/nse/core/netns_controller.py +1066 -0
  12. network_sandbox_engine-2.2.0/nse/core/pipeline.py +693 -0
  13. network_sandbox_engine-2.2.0/nse/core/process.py +768 -0
  14. network_sandbox_engine-2.2.0/nse/core/resource_network.py +161 -0
  15. network_sandbox_engine-2.2.0/nse/core/resource_registry.py +365 -0
  16. network_sandbox_engine-2.2.0/nse/core/sniffer.py +779 -0
  17. network_sandbox_engine-2.2.0/nse/core/trace_attribution.py +61 -0
  18. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/trace_harvester.py +44 -4
  19. network_sandbox_engine-2.2.0/nse/core/verdicts.py +64 -0
  20. network_sandbox_engine-2.2.0/nse/models/artifacts.py +73 -0
  21. network_sandbox_engine-2.2.0/nse/models/capture_report.py +219 -0
  22. network_sandbox_engine-2.2.0/nse/models/experiment_report.py +266 -0
  23. network_sandbox_engine-2.2.0/nse/models/network_config.py +57 -0
  24. network_sandbox_engine-2.2.0/nse/models/process.py +271 -0
  25. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/test_request.py +17 -1
  26. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/trace_event.py +9 -0
  27. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/pyproject.toml +2 -1
  28. network_sandbox_engine-2.2.0/tests/test_api_compat.py +179 -0
  29. network_sandbox_engine-2.2.0/tests/test_async_work.py +62 -0
  30. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_engine_internals.py +181 -28
  31. network_sandbox_engine-2.2.0/tests/test_examples.py +127 -0
  32. network_sandbox_engine-2.2.0/tests/test_exec_argv.py +177 -0
  33. network_sandbox_engine-2.2.0/tests/test_experiment_report.py +451 -0
  34. network_sandbox_engine-2.2.0/tests/test_experiment_report_integration.py +96 -0
  35. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_netns.py +26 -36
  36. network_sandbox_engine-2.2.0/tests/test_network_config.py +82 -0
  37. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_paths.py +82 -9
  38. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_pipeline_unit.py +76 -27
  39. network_sandbox_engine-2.2.0/tests/test_process.py +842 -0
  40. network_sandbox_engine-2.2.0/tests/test_process_integration.py +248 -0
  41. network_sandbox_engine-2.2.0/tests/test_resource_lifecycle.py +263 -0
  42. network_sandbox_engine-2.2.0/tests/test_resource_ownership.py +538 -0
  43. network_sandbox_engine-2.2.0/tests/test_resource_registry.py +305 -0
  44. network_sandbox_engine-2.2.0/tests/test_runner_cli.py +478 -0
  45. network_sandbox_engine-2.2.0/tests/test_sniffer.py +972 -0
  46. network_sandbox_engine-2.2.0/tests/test_sniffer_integration.py +287 -0
  47. network_sandbox_engine-2.2.0/tests/test_topology_concurrency.py +336 -0
  48. network_sandbox_engine-2.2.0/tests/test_trace_attribution.py +118 -0
  49. network_sandbox_engine-2.1.1/nse/__init__.py +0 -20
  50. network_sandbox_engine-2.1.1/nse/core/netns_controller.py +0 -614
  51. network_sandbox_engine-2.1.1/nse/core/pipeline.py +0 -537
  52. network_sandbox_engine-2.1.1/nse/core/sniffer.py +0 -57
  53. network_sandbox_engine-2.1.1/tests/test_runner_cli.py +0 -195
  54. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/LICENSE +0 -0
  55. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/dependency_links.txt +0 -0
  56. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/entry_points.txt +0 -0
  57. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/requires.txt +0 -0
  58. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/top_level.txt +0 -0
  59. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/cli/__init__.py +0 -0
  60. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/__init__.py +0 -0
  61. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/paths.py +0 -0
  62. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/rule_engine.py +0 -0
  63. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/scapy_injector.py +0 -0
  64. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/utils.py +0 -0
  65. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/__init__.py +0 -0
  66. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/setup.cfg +0 -0
  67. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_docs_examples.py +0 -0
  68. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_oracle_e2e.py +0 -0
  69. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_runner_logic.py +0 -0
  70. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_trace_harvester.py +0 -0
  71. {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_trace_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: network-sandbox-engine
3
- Version: 2.1.1
3
+ Version: 2.2.0
4
4
  Summary: Headless Python engine for isolated network namespace testing and PCAP assertions.
5
5
  Author: onyks
6
6
  License-Expression: MIT
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3
15
15
  Classifier: Programming Language :: Python :: 3.10
16
16
  Classifier: Programming Language :: Python :: 3.11
17
17
  Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
18
19
  Classifier: Topic :: System :: Networking
19
20
  Classifier: Topic :: Software Development :: Testing
20
21
  Requires-Python: >=3.10
@@ -45,9 +46,15 @@ Copyright (c) 2026 onyks-os
45
46
  SPDX-License-Identifier: MIT
46
47
  -->
47
48
 
48
- <h1 align="center">
49
+ <p align="center">
50
+ <img src="https://raw.githubusercontent.com/onyks-os/NetworkSandboxEngine/main/assets/logo.svg" alt="Network Sandbox Engine" width="720">
51
+ </p>
52
+
53
+ <!-- --- -->
54
+
55
+ <!-- <h1 align="center">
49
56
  Network Sandbox Engine (NSE)
50
- </h1>
57
+ </h1> -->
51
58
 
52
59
  <h4 align="center">A Linux engine for deterministic <b>nftables firewall testing</b> inside isolated network namespaces.</h4>
53
60
 
@@ -62,22 +69,17 @@ SPDX-License-Identifier: MIT
62
69
 
63
70
  <p align="center">
64
71
  <a href="#why-nse">Why NSE?</a> •
72
+ <a href="#the-oracle-contract">Oracle contract</a> •
73
+ <a href="#asserting-on-the-wire">Wire assertions</a> •
65
74
  <a href="#features">Features</a> •
66
75
  <a href="#requirements">Requirements</a> •
67
76
  <a href="#installation">Installation</a> •
68
77
  <a href="#quickstart">Quickstart</a> •
78
+ <a href="#examples">Examples</a> •
69
79
  <a href="#how-it-works">How It Works</a> •
70
80
  <a href="#project-structure">Project Structure</a>
71
81
  </p>
72
82
 
73
- ---
74
-
75
- <p align="center">
76
- <img src="assets/preview.png" alt="Network Sandbox Engine Interface" width="800">
77
- </p>
78
-
79
- ---
80
-
81
83
  ## Why NSE?
82
84
 
83
85
  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.
@@ -86,10 +88,28 @@ Network Sandbox Engine (NSE) provides a safe, reproducible testing harness. It c
86
88
 
87
89
  Key architectural properties:
88
90
 
89
- * **Zero Host Mutation**: Rulesets are loaded exclusively into ephemeral sandbox namespaces (`nse_<uuid>`) and are completely removed during teardown.
91
+ * **The host firewall is never touched**: the ruleset under test is loaded only inside the sandbox namespaces. What a run does create on the host is temporary and declared; see [What a run changes on the host](#what-a-run-changes-on-the-host).
90
92
  * **Self-verifying Oracle**: Every run injects a *canary* packet before the test packets and again after them, and reports a result only if the kernel trace for both was observed. See [The oracle contract](#the-oracle-contract).
91
93
  * **Dual-Stack and Topologies**: Native support for IPv4 and IPv6 traffic, plus multi-namespace Gateway topologies for router, NAT, and forwarding ruleset validation.
92
- * **Small, auditable surface**: One package, no web server, no JavaScript. `nse/` is ~1150 statements at 98% test coverage.
94
+ * **Small, auditable surface**: One package, no web server, no JavaScript, with 98% test coverage enforced by a ratchet.
95
+
96
+ ### What a run changes on the host
97
+
98
+ | Changed | Not changed |
99
+ | :--- | :--- |
100
+ | Network namespaces `nse_*` (`/var/run/netns`) | The host's nftables or iptables ruleset |
101
+ | The host end of each veth link (`vhr-*`), with its addresses | Host sysctls: forwarding and DAD settings are set inside the namespaces |
102
+ | In the gateway topology, routes to the sandbox subnets via that link | Existing interfaces, addresses and routes |
103
+ | Ownership journals and locks under `/run/nse` | Anything outside the run's own records |
104
+
105
+ Every one of these is recorded in an ownership journal before it is created,
106
+ and removed at teardown, or by the next NSE start if a run was killed.
107
+ Processes still running in a sandbox namespace are stopped before it is deleted.
108
+
109
+ Setup refuses to start rather than shadow anything: an interface name already in
110
+ use, or a sandbox subnet overlapping an existing host route, is an error before
111
+ the kernel is touched. A cleanup that cannot prove ownership preserves the
112
+ resource and says so.
93
113
 
94
114
  ### Requires root
95
115
 
@@ -131,6 +151,48 @@ non-zero. That job runs in CI on every push.
131
151
 
132
152
  ---
133
153
 
154
+ ## Asserting on the wire
155
+
156
+ `nft monitor trace` reports what the ruleset *decided*. It cannot report what
157
+ left an interface the ruleset never matched on, which is the question a
158
+ zero-leak claim actually asks. `PCAPAsserter` covers that: it captures on a
159
+ named interface, so a test can assert that a stimulus produced **no** frame.
160
+
161
+ ```python
162
+ from nse import PCAPAsserter
163
+
164
+ asserter = PCAPAsserter(iface="vhr-...")
165
+ await asserter.start() # returns once the kernel socket is filtering and bound
166
+ # ... send the stimulus ...
167
+ leaked = await asserter.stop() # raises CaptureError if the capture broke
168
+ assert not leaked, leaked
169
+ ```
170
+
171
+ `stop()` raises when the capture itself failed, and `stop_report()` says
172
+ whether the window was complete. Long captures can go to a PCAP file with
173
+ bounded memory.
174
+
175
+ None of that proves the capture was watching the path the stimulus took.
176
+ Readiness means the socket was armed on *that* interface; it does not mean the
177
+ stimulus crosses it. That evidence is the caller's to provide: capture the
178
+ stimulus once where it must be seen, and require it to be *seen* before
179
+ asserting its absence. [`examples/broken_observer.py`](examples/broken_observer.py)
180
+ shows the claim "nothing leaves" passing on the wrong interface, and its
181
+ positive control rejecting it.
182
+
183
+ **The default filter suppresses link-local noise, and nothing else.**
184
+ `DEFAULT_FILTER` excludes ARP and ICMPv6 types 133-137 - Neighbour Discovery,
185
+ which carries a hop limit of 255 and cannot reach a remote observer. Everything
186
+ else is captured, including ICMPv6 echo to a globally routable address. A
187
+ `filter` argument is combined with that default; `replace_default_filter=True`
188
+ uses yours alone. The escape hatch exists because the filter is compiled into
189
+ BPF and evaluated in the kernel: a packet it excludes never reaches userspace,
190
+ so no consumer can recover it downstream. Until 2.1.2 the default read `not arp
191
+ and not icmp6`, which discarded routable ICMPv6 as well - see
192
+ [issue #14](https://github.com/onyks-os/NetworkSandboxEngine/issues/14).
193
+
194
+ ---
195
+
134
196
  ## Features
135
197
 
136
198
  * **In-Process Engine**: Direct Python API (`run_test_pipeline`) returning structured Pydantic models (`TestRequest`, `TraceEvent`).
@@ -138,9 +200,12 @@ non-zero. That job runs in CI on every push.
138
200
  * **Isolated Topologies**:
139
201
  * **Simple**: Single sandbox namespace (`nse_<id>`) wired directly to the host.
140
202
  * **Gateway**: Router (`nse_router_<id>`) and Server (`nse_server_<id>`) chain for forwarding and NAT testing.
141
- * **Automated Cleanup**: Startup sweeps detect and remove leftover namespaces and veth pairs from previous aborted runs. Teardowns include exponential backoff retries.
142
- * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict *and* on a verdict it failed to observe.
143
- * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make test-cov`, floor 98%).
203
+ * **Wire-level Leak Assertions**: `PCAPAsserter` captures on a named interface so a test can assert that a stimulus produced no frame at all. See [Asserting on the wire](#asserting-on-the-wire).
204
+ * **Ownership-aware Cleanup**: Private journals and owner locks protect active runs. Startup recovery removes only verified abandoned resources; prefix matches without ownership evidence are preserved. Failed teardowns retain their records for retry. See [Namespace lifecycle](docs/web/explanation/namespace-lifecycle.md).
205
+ * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict, on a verdict it failed to observe, and on a run that did not clean up. `--report-dir` keeps a JSON report and a SHA-256 manifest.
206
+ * **Reproducible experiment reports**: `run_test_pipeline_report()` records input, environment, outcome, observations and timings, so a CI artifact is enough to reconstruct a run.
207
+ * **Managed application processes**: real servers and clients run in the sandbox with a verified UID, GID and capabilities, timeouts, and a namespace-wide process boundary.
208
+ * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make coverage`, floor 98%).
144
209
 
145
210
  ---
146
211
 
@@ -170,6 +235,11 @@ Install the core engine with CLI support:
170
235
  pip install "network-sandbox-engine[cli]"
171
236
  ```
172
237
 
238
+ Upgrading from 2.1.x needs no code change: the 2.1.2 API is checked by a test
239
+ and on the installed packages. Some silent failures are now errors, and some
240
+ workarounds are no longer needed. See
241
+ [Upgrading to 2.2](https://onyks-os.github.io/nse/release-notes/upgrading-to-2.2/).
242
+
173
243
  ### 2. Manual Source Install
174
244
 
175
245
  For local development:
@@ -275,6 +345,45 @@ Useful for pinning the nftables version your rules are tested against.
275
345
 
276
346
  ---
277
347
 
348
+ ## Examples
349
+
350
+ [`examples/`](examples/) holds complete experiments, each with its input and
351
+ expected output. CI runs every one of them on a real kernel:
352
+
353
+ | Example | Shows |
354
+ | :--- | :--- |
355
+ | [`workstation.yaml`](examples/workstation.yaml) | A drop-by-default workstation policy, IPv4 and IPv6 |
356
+ | [`ipv6.yaml`](examples/ipv6.yaml) | A service published over IPv6 only |
357
+ | [`coexistence.yaml`](examples/coexistence.yaml) | An accept in one table does not override a drop in another |
358
+ | [`gateway_nat.yaml`](examples/gateway_nat.yaml) | Forwarding and masquerade through the gateway topology |
359
+ | [`real_application.py`](examples/real_application.py) | A real TCP/UDP server as `nobody`, a bounded file capture, positive controls |
360
+ | [`broken_policy.py`](examples/broken_policy.py) | A wrong ruleset with a sound observer: caught |
361
+ | [`broken_observer.py`](examples/broken_observer.py) | A blind oracle and a misplaced capture: both caught |
362
+
363
+ ```bash
364
+ sudo nse-runner --file examples/gateway_nat.yaml
365
+ sudo python3 examples/real_application.py
366
+ ```
367
+
368
+ ### Who relies on NSE, and what stays with them
369
+
370
+ NSE is qualified against two independent consumers. One is
371
+ [TransparentTorProxy](https://github.com/onyks-os/TransparentTorProxy) (TTP).
372
+ Its test suite drives NSE's controller, rule engine, trace harvester, mock
373
+ listeners and `PCAPAsserter` for rule and leak-containment tests. The other is
374
+ the NAT gateway example above, which needs nothing from TTP. NSE guarantees the
375
+ measurement: an observed verdict, a confirmed capture, a verified process
376
+ identity, a clean teardown. Some decisions stay with the consumer:
377
+
378
+ * which verdicts are correct, and what counts as a leak;
379
+ * which positive control proves that a capture watches the path a stimulus
380
+ takes;
381
+ * the topology and addresses, including a host whose routes collide with the
382
+ defaults;
383
+ * retries, and what a failed run blocks in their pipeline.
384
+
385
+ ---
386
+
278
387
  ## How It Works
279
388
 
280
389
  NSE orchestrates Linux kernel network subsystems and trace interfaces through a structured multi-stage execution pipeline:
@@ -372,7 +481,7 @@ Run static linting and unit tests:
372
481
  make verify
373
482
  ```
374
483
 
375
- Run full local CI verification (includes linting, unit tests, frontend build, docs build, PyPI smoke test, and privileged integration tests):
484
+ Run the full local CI pipeline (lint, type check, import boundaries, unit tests, docs build, and the release artifacts):
376
485
 
377
486
  ```bash
378
487
  make ci-local
@@ -3,9 +3,15 @@ Copyright (c) 2026 onyks-os
3
3
  SPDX-License-Identifier: MIT
4
4
  -->
5
5
 
6
- <h1 align="center">
6
+ <p align="center">
7
+ <img src="https://raw.githubusercontent.com/onyks-os/NetworkSandboxEngine/main/assets/logo.svg" alt="Network Sandbox Engine" width="720">
8
+ </p>
9
+
10
+ <!-- --- -->
11
+
12
+ <!-- <h1 align="center">
7
13
  Network Sandbox Engine (NSE)
8
- </h1>
14
+ </h1> -->
9
15
 
10
16
  <h4 align="center">A Linux engine for deterministic <b>nftables firewall testing</b> inside isolated network namespaces.</h4>
11
17
 
@@ -20,22 +26,17 @@ SPDX-License-Identifier: MIT
20
26
 
21
27
  <p align="center">
22
28
  <a href="#why-nse">Why NSE?</a> •
29
+ <a href="#the-oracle-contract">Oracle contract</a> •
30
+ <a href="#asserting-on-the-wire">Wire assertions</a> •
23
31
  <a href="#features">Features</a> •
24
32
  <a href="#requirements">Requirements</a> •
25
33
  <a href="#installation">Installation</a> •
26
34
  <a href="#quickstart">Quickstart</a> •
35
+ <a href="#examples">Examples</a> •
27
36
  <a href="#how-it-works">How It Works</a> •
28
37
  <a href="#project-structure">Project Structure</a>
29
38
  </p>
30
39
 
31
- ---
32
-
33
- <p align="center">
34
- <img src="assets/preview.png" alt="Network Sandbox Engine Interface" width="800">
35
- </p>
36
-
37
- ---
38
-
39
40
  ## Why NSE?
40
41
 
41
42
  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.
@@ -44,10 +45,28 @@ Network Sandbox Engine (NSE) provides a safe, reproducible testing harness. It c
44
45
 
45
46
  Key architectural properties:
46
47
 
47
- * **Zero Host Mutation**: Rulesets are loaded exclusively into ephemeral sandbox namespaces (`nse_<uuid>`) and are completely removed during teardown.
48
+ * **The host firewall is never touched**: the ruleset under test is loaded only inside the sandbox namespaces. What a run does create on the host is temporary and declared; see [What a run changes on the host](#what-a-run-changes-on-the-host).
48
49
  * **Self-verifying Oracle**: Every run injects a *canary* packet before the test packets and again after them, and reports a result only if the kernel trace for both was observed. See [The oracle contract](#the-oracle-contract).
49
50
  * **Dual-Stack and Topologies**: Native support for IPv4 and IPv6 traffic, plus multi-namespace Gateway topologies for router, NAT, and forwarding ruleset validation.
50
- * **Small, auditable surface**: One package, no web server, no JavaScript. `nse/` is ~1150 statements at 98% test coverage.
51
+ * **Small, auditable surface**: One package, no web server, no JavaScript, with 98% test coverage enforced by a ratchet.
52
+
53
+ ### What a run changes on the host
54
+
55
+ | Changed | Not changed |
56
+ | :--- | :--- |
57
+ | Network namespaces `nse_*` (`/var/run/netns`) | The host's nftables or iptables ruleset |
58
+ | The host end of each veth link (`vhr-*`), with its addresses | Host sysctls: forwarding and DAD settings are set inside the namespaces |
59
+ | In the gateway topology, routes to the sandbox subnets via that link | Existing interfaces, addresses and routes |
60
+ | Ownership journals and locks under `/run/nse` | Anything outside the run's own records |
61
+
62
+ Every one of these is recorded in an ownership journal before it is created,
63
+ and removed at teardown, or by the next NSE start if a run was killed.
64
+ Processes still running in a sandbox namespace are stopped before it is deleted.
65
+
66
+ Setup refuses to start rather than shadow anything: an interface name already in
67
+ use, or a sandbox subnet overlapping an existing host route, is an error before
68
+ the kernel is touched. A cleanup that cannot prove ownership preserves the
69
+ resource and says so.
51
70
 
52
71
  ### Requires root
53
72
 
@@ -89,6 +108,48 @@ non-zero. That job runs in CI on every push.
89
108
 
90
109
  ---
91
110
 
111
+ ## Asserting on the wire
112
+
113
+ `nft monitor trace` reports what the ruleset *decided*. It cannot report what
114
+ left an interface the ruleset never matched on, which is the question a
115
+ zero-leak claim actually asks. `PCAPAsserter` covers that: it captures on a
116
+ named interface, so a test can assert that a stimulus produced **no** frame.
117
+
118
+ ```python
119
+ from nse import PCAPAsserter
120
+
121
+ asserter = PCAPAsserter(iface="vhr-...")
122
+ await asserter.start() # returns once the kernel socket is filtering and bound
123
+ # ... send the stimulus ...
124
+ leaked = await asserter.stop() # raises CaptureError if the capture broke
125
+ assert not leaked, leaked
126
+ ```
127
+
128
+ `stop()` raises when the capture itself failed, and `stop_report()` says
129
+ whether the window was complete. Long captures can go to a PCAP file with
130
+ bounded memory.
131
+
132
+ None of that proves the capture was watching the path the stimulus took.
133
+ Readiness means the socket was armed on *that* interface; it does not mean the
134
+ stimulus crosses it. That evidence is the caller's to provide: capture the
135
+ stimulus once where it must be seen, and require it to be *seen* before
136
+ asserting its absence. [`examples/broken_observer.py`](examples/broken_observer.py)
137
+ shows the claim "nothing leaves" passing on the wrong interface, and its
138
+ positive control rejecting it.
139
+
140
+ **The default filter suppresses link-local noise, and nothing else.**
141
+ `DEFAULT_FILTER` excludes ARP and ICMPv6 types 133-137 - Neighbour Discovery,
142
+ which carries a hop limit of 255 and cannot reach a remote observer. Everything
143
+ else is captured, including ICMPv6 echo to a globally routable address. A
144
+ `filter` argument is combined with that default; `replace_default_filter=True`
145
+ uses yours alone. The escape hatch exists because the filter is compiled into
146
+ BPF and evaluated in the kernel: a packet it excludes never reaches userspace,
147
+ so no consumer can recover it downstream. Until 2.1.2 the default read `not arp
148
+ and not icmp6`, which discarded routable ICMPv6 as well - see
149
+ [issue #14](https://github.com/onyks-os/NetworkSandboxEngine/issues/14).
150
+
151
+ ---
152
+
92
153
  ## Features
93
154
 
94
155
  * **In-Process Engine**: Direct Python API (`run_test_pipeline`) returning structured Pydantic models (`TestRequest`, `TraceEvent`).
@@ -96,9 +157,12 @@ non-zero. That job runs in CI on every push.
96
157
  * **Isolated Topologies**:
97
158
  * **Simple**: Single sandbox namespace (`nse_<id>`) wired directly to the host.
98
159
  * **Gateway**: Router (`nse_router_<id>`) and Server (`nse_server_<id>`) chain for forwarding and NAT testing.
99
- * **Automated Cleanup**: Startup sweeps detect and remove leftover namespaces and veth pairs from previous aborted runs. Teardowns include exponential backoff retries.
100
- * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict *and* on a verdict it failed to observe.
101
- * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make test-cov`, floor 98%).
160
+ * **Wire-level Leak Assertions**: `PCAPAsserter` captures on a named interface so a test can assert that a stimulus produced no frame at all. See [Asserting on the wire](#asserting-on-the-wire).
161
+ * **Ownership-aware Cleanup**: Private journals and owner locks protect active runs. Startup recovery removes only verified abandoned resources; prefix matches without ownership evidence are preserved. Failed teardowns retain their records for retry. See [Namespace lifecycle](docs/web/explanation/namespace-lifecycle.md).
162
+ * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict, on a verdict it failed to observe, and on a run that did not clean up. `--report-dir` keeps a JSON report and a SHA-256 manifest.
163
+ * **Reproducible experiment reports**: `run_test_pipeline_report()` records input, environment, outcome, observations and timings, so a CI artifact is enough to reconstruct a run.
164
+ * **Managed application processes**: real servers and clients run in the sandbox with a verified UID, GID and capabilities, timeouts, and a namespace-wide process boundary.
165
+ * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make coverage`, floor 98%).
102
166
 
103
167
  ---
104
168
 
@@ -128,6 +192,11 @@ Install the core engine with CLI support:
128
192
  pip install "network-sandbox-engine[cli]"
129
193
  ```
130
194
 
195
+ Upgrading from 2.1.x needs no code change: the 2.1.2 API is checked by a test
196
+ and on the installed packages. Some silent failures are now errors, and some
197
+ workarounds are no longer needed. See
198
+ [Upgrading to 2.2](https://onyks-os.github.io/nse/release-notes/upgrading-to-2.2/).
199
+
131
200
  ### 2. Manual Source Install
132
201
 
133
202
  For local development:
@@ -233,6 +302,45 @@ Useful for pinning the nftables version your rules are tested against.
233
302
 
234
303
  ---
235
304
 
305
+ ## Examples
306
+
307
+ [`examples/`](examples/) holds complete experiments, each with its input and
308
+ expected output. CI runs every one of them on a real kernel:
309
+
310
+ | Example | Shows |
311
+ | :--- | :--- |
312
+ | [`workstation.yaml`](examples/workstation.yaml) | A drop-by-default workstation policy, IPv4 and IPv6 |
313
+ | [`ipv6.yaml`](examples/ipv6.yaml) | A service published over IPv6 only |
314
+ | [`coexistence.yaml`](examples/coexistence.yaml) | An accept in one table does not override a drop in another |
315
+ | [`gateway_nat.yaml`](examples/gateway_nat.yaml) | Forwarding and masquerade through the gateway topology |
316
+ | [`real_application.py`](examples/real_application.py) | A real TCP/UDP server as `nobody`, a bounded file capture, positive controls |
317
+ | [`broken_policy.py`](examples/broken_policy.py) | A wrong ruleset with a sound observer: caught |
318
+ | [`broken_observer.py`](examples/broken_observer.py) | A blind oracle and a misplaced capture: both caught |
319
+
320
+ ```bash
321
+ sudo nse-runner --file examples/gateway_nat.yaml
322
+ sudo python3 examples/real_application.py
323
+ ```
324
+
325
+ ### Who relies on NSE, and what stays with them
326
+
327
+ NSE is qualified against two independent consumers. One is
328
+ [TransparentTorProxy](https://github.com/onyks-os/TransparentTorProxy) (TTP).
329
+ Its test suite drives NSE's controller, rule engine, trace harvester, mock
330
+ listeners and `PCAPAsserter` for rule and leak-containment tests. The other is
331
+ the NAT gateway example above, which needs nothing from TTP. NSE guarantees the
332
+ measurement: an observed verdict, a confirmed capture, a verified process
333
+ identity, a clean teardown. Some decisions stay with the consumer:
334
+
335
+ * which verdicts are correct, and what counts as a leak;
336
+ * which positive control proves that a capture watches the path a stimulus
337
+ takes;
338
+ * the topology and addresses, including a host whose routes collide with the
339
+ defaults;
340
+ * retries, and what a failed run blocks in their pipeline.
341
+
342
+ ---
343
+
236
344
  ## How It Works
237
345
 
238
346
  NSE orchestrates Linux kernel network subsystems and trace interfaces through a structured multi-stage execution pipeline:
@@ -330,7 +438,7 @@ Run static linting and unit tests:
330
438
  make verify
331
439
  ```
332
440
 
333
- Run full local CI verification (includes linting, unit tests, frontend build, docs build, PyPI smoke test, and privileged integration tests):
441
+ Run the full local CI pipeline (lint, type check, import boundaries, unit tests, docs build, and the release artifacts):
334
442
 
335
443
  ```bash
336
444
  make ci-local
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: network-sandbox-engine
3
- Version: 2.1.1
3
+ Version: 2.2.0
4
4
  Summary: Headless Python engine for isolated network namespace testing and PCAP assertions.
5
5
  Author: onyks
6
6
  License-Expression: MIT
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3
15
15
  Classifier: Programming Language :: Python :: 3.10
16
16
  Classifier: Programming Language :: Python :: 3.11
17
17
  Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
18
19
  Classifier: Topic :: System :: Networking
19
20
  Classifier: Topic :: Software Development :: Testing
20
21
  Requires-Python: >=3.10
@@ -45,9 +46,15 @@ Copyright (c) 2026 onyks-os
45
46
  SPDX-License-Identifier: MIT
46
47
  -->
47
48
 
48
- <h1 align="center">
49
+ <p align="center">
50
+ <img src="https://raw.githubusercontent.com/onyks-os/NetworkSandboxEngine/main/assets/logo.svg" alt="Network Sandbox Engine" width="720">
51
+ </p>
52
+
53
+ <!-- --- -->
54
+
55
+ <!-- <h1 align="center">
49
56
  Network Sandbox Engine (NSE)
50
- </h1>
57
+ </h1> -->
51
58
 
52
59
  <h4 align="center">A Linux engine for deterministic <b>nftables firewall testing</b> inside isolated network namespaces.</h4>
53
60
 
@@ -62,22 +69,17 @@ SPDX-License-Identifier: MIT
62
69
 
63
70
  <p align="center">
64
71
  <a href="#why-nse">Why NSE?</a> •
72
+ <a href="#the-oracle-contract">Oracle contract</a> •
73
+ <a href="#asserting-on-the-wire">Wire assertions</a> •
65
74
  <a href="#features">Features</a> •
66
75
  <a href="#requirements">Requirements</a> •
67
76
  <a href="#installation">Installation</a> •
68
77
  <a href="#quickstart">Quickstart</a> •
78
+ <a href="#examples">Examples</a> •
69
79
  <a href="#how-it-works">How It Works</a> •
70
80
  <a href="#project-structure">Project Structure</a>
71
81
  </p>
72
82
 
73
- ---
74
-
75
- <p align="center">
76
- <img src="assets/preview.png" alt="Network Sandbox Engine Interface" width="800">
77
- </p>
78
-
79
- ---
80
-
81
83
  ## Why NSE?
82
84
 
83
85
  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.
@@ -86,10 +88,28 @@ Network Sandbox Engine (NSE) provides a safe, reproducible testing harness. It c
86
88
 
87
89
  Key architectural properties:
88
90
 
89
- * **Zero Host Mutation**: Rulesets are loaded exclusively into ephemeral sandbox namespaces (`nse_<uuid>`) and are completely removed during teardown.
91
+ * **The host firewall is never touched**: the ruleset under test is loaded only inside the sandbox namespaces. What a run does create on the host is temporary and declared; see [What a run changes on the host](#what-a-run-changes-on-the-host).
90
92
  * **Self-verifying Oracle**: Every run injects a *canary* packet before the test packets and again after them, and reports a result only if the kernel trace for both was observed. See [The oracle contract](#the-oracle-contract).
91
93
  * **Dual-Stack and Topologies**: Native support for IPv4 and IPv6 traffic, plus multi-namespace Gateway topologies for router, NAT, and forwarding ruleset validation.
92
- * **Small, auditable surface**: One package, no web server, no JavaScript. `nse/` is ~1150 statements at 98% test coverage.
94
+ * **Small, auditable surface**: One package, no web server, no JavaScript, with 98% test coverage enforced by a ratchet.
95
+
96
+ ### What a run changes on the host
97
+
98
+ | Changed | Not changed |
99
+ | :--- | :--- |
100
+ | Network namespaces `nse_*` (`/var/run/netns`) | The host's nftables or iptables ruleset |
101
+ | The host end of each veth link (`vhr-*`), with its addresses | Host sysctls: forwarding and DAD settings are set inside the namespaces |
102
+ | In the gateway topology, routes to the sandbox subnets via that link | Existing interfaces, addresses and routes |
103
+ | Ownership journals and locks under `/run/nse` | Anything outside the run's own records |
104
+
105
+ Every one of these is recorded in an ownership journal before it is created,
106
+ and removed at teardown, or by the next NSE start if a run was killed.
107
+ Processes still running in a sandbox namespace are stopped before it is deleted.
108
+
109
+ Setup refuses to start rather than shadow anything: an interface name already in
110
+ use, or a sandbox subnet overlapping an existing host route, is an error before
111
+ the kernel is touched. A cleanup that cannot prove ownership preserves the
112
+ resource and says so.
93
113
 
94
114
  ### Requires root
95
115
 
@@ -131,6 +151,48 @@ non-zero. That job runs in CI on every push.
131
151
 
132
152
  ---
133
153
 
154
+ ## Asserting on the wire
155
+
156
+ `nft monitor trace` reports what the ruleset *decided*. It cannot report what
157
+ left an interface the ruleset never matched on, which is the question a
158
+ zero-leak claim actually asks. `PCAPAsserter` covers that: it captures on a
159
+ named interface, so a test can assert that a stimulus produced **no** frame.
160
+
161
+ ```python
162
+ from nse import PCAPAsserter
163
+
164
+ asserter = PCAPAsserter(iface="vhr-...")
165
+ await asserter.start() # returns once the kernel socket is filtering and bound
166
+ # ... send the stimulus ...
167
+ leaked = await asserter.stop() # raises CaptureError if the capture broke
168
+ assert not leaked, leaked
169
+ ```
170
+
171
+ `stop()` raises when the capture itself failed, and `stop_report()` says
172
+ whether the window was complete. Long captures can go to a PCAP file with
173
+ bounded memory.
174
+
175
+ None of that proves the capture was watching the path the stimulus took.
176
+ Readiness means the socket was armed on *that* interface; it does not mean the
177
+ stimulus crosses it. That evidence is the caller's to provide: capture the
178
+ stimulus once where it must be seen, and require it to be *seen* before
179
+ asserting its absence. [`examples/broken_observer.py`](examples/broken_observer.py)
180
+ shows the claim "nothing leaves" passing on the wrong interface, and its
181
+ positive control rejecting it.
182
+
183
+ **The default filter suppresses link-local noise, and nothing else.**
184
+ `DEFAULT_FILTER` excludes ARP and ICMPv6 types 133-137 - Neighbour Discovery,
185
+ which carries a hop limit of 255 and cannot reach a remote observer. Everything
186
+ else is captured, including ICMPv6 echo to a globally routable address. A
187
+ `filter` argument is combined with that default; `replace_default_filter=True`
188
+ uses yours alone. The escape hatch exists because the filter is compiled into
189
+ BPF and evaluated in the kernel: a packet it excludes never reaches userspace,
190
+ so no consumer can recover it downstream. Until 2.1.2 the default read `not arp
191
+ and not icmp6`, which discarded routable ICMPv6 as well - see
192
+ [issue #14](https://github.com/onyks-os/NetworkSandboxEngine/issues/14).
193
+
194
+ ---
195
+
134
196
  ## Features
135
197
 
136
198
  * **In-Process Engine**: Direct Python API (`run_test_pipeline`) returning structured Pydantic models (`TestRequest`, `TraceEvent`).
@@ -138,9 +200,12 @@ non-zero. That job runs in CI on every push.
138
200
  * **Isolated Topologies**:
139
201
  * **Simple**: Single sandbox namespace (`nse_<id>`) wired directly to the host.
140
202
  * **Gateway**: Router (`nse_router_<id>`) and Server (`nse_server_<id>`) chain for forwarding and NAT testing.
141
- * **Automated Cleanup**: Startup sweeps detect and remove leftover namespaces and veth pairs from previous aborted runs. Teardowns include exponential backoff retries.
142
- * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict *and* on a verdict it failed to observe.
143
- * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make test-cov`, floor 98%).
203
+ * **Wire-level Leak Assertions**: `PCAPAsserter` captures on a named interface so a test can assert that a stimulus produced no frame at all. See [Asserting on the wire](#asserting-on-the-wire).
204
+ * **Ownership-aware Cleanup**: Private journals and owner locks protect active runs. Startup recovery removes only verified abandoned resources; prefix matches without ownership evidence are preserved. Failed teardowns retain their records for retry. See [Namespace lifecycle](docs/web/explanation/namespace-lifecycle.md).
205
+ * **CLI YAML Test Runner**: Execute declarative YAML test suites for automated CI/CD pipelines (`nse-runner`). Exits non-zero on a wrong verdict, on a verdict it failed to observe, and on a run that did not clean up. `--report-dir` keeps a JSON report and a SHA-256 manifest.
206
+ * **Reproducible experiment reports**: `run_test_pipeline_report()` records input, environment, outcome, observations and timings, so a CI artifact is enough to reconstruct a run.
207
+ * **Managed application processes**: real servers and clients run in the sandbox with a verified UID, GID and capabilities, timeouts, and a namespace-wide process boundary.
208
+ * **Strict Quality Standards**: Full static type checking (`mypy --strict`), architectural boundary enforcement (`import-linter`), `ruff` formatting, and a coverage ratchet (`make coverage`, floor 98%).
144
209
 
145
210
  ---
146
211
 
@@ -170,6 +235,11 @@ Install the core engine with CLI support:
170
235
  pip install "network-sandbox-engine[cli]"
171
236
  ```
172
237
 
238
+ Upgrading from 2.1.x needs no code change: the 2.1.2 API is checked by a test
239
+ and on the installed packages. Some silent failures are now errors, and some
240
+ workarounds are no longer needed. See
241
+ [Upgrading to 2.2](https://onyks-os.github.io/nse/release-notes/upgrading-to-2.2/).
242
+
173
243
  ### 2. Manual Source Install
174
244
 
175
245
  For local development:
@@ -275,6 +345,45 @@ Useful for pinning the nftables version your rules are tested against.
275
345
 
276
346
  ---
277
347
 
348
+ ## Examples
349
+
350
+ [`examples/`](examples/) holds complete experiments, each with its input and
351
+ expected output. CI runs every one of them on a real kernel:
352
+
353
+ | Example | Shows |
354
+ | :--- | :--- |
355
+ | [`workstation.yaml`](examples/workstation.yaml) | A drop-by-default workstation policy, IPv4 and IPv6 |
356
+ | [`ipv6.yaml`](examples/ipv6.yaml) | A service published over IPv6 only |
357
+ | [`coexistence.yaml`](examples/coexistence.yaml) | An accept in one table does not override a drop in another |
358
+ | [`gateway_nat.yaml`](examples/gateway_nat.yaml) | Forwarding and masquerade through the gateway topology |
359
+ | [`real_application.py`](examples/real_application.py) | A real TCP/UDP server as `nobody`, a bounded file capture, positive controls |
360
+ | [`broken_policy.py`](examples/broken_policy.py) | A wrong ruleset with a sound observer: caught |
361
+ | [`broken_observer.py`](examples/broken_observer.py) | A blind oracle and a misplaced capture: both caught |
362
+
363
+ ```bash
364
+ sudo nse-runner --file examples/gateway_nat.yaml
365
+ sudo python3 examples/real_application.py
366
+ ```
367
+
368
+ ### Who relies on NSE, and what stays with them
369
+
370
+ NSE is qualified against two independent consumers. One is
371
+ [TransparentTorProxy](https://github.com/onyks-os/TransparentTorProxy) (TTP).
372
+ Its test suite drives NSE's controller, rule engine, trace harvester, mock
373
+ listeners and `PCAPAsserter` for rule and leak-containment tests. The other is
374
+ the NAT gateway example above, which needs nothing from TTP. NSE guarantees the
375
+ measurement: an observed verdict, a confirmed capture, a verified process
376
+ identity, a clean teardown. Some decisions stay with the consumer:
377
+
378
+ * which verdicts are correct, and what counts as a leak;
379
+ * which positive control proves that a capture watches the path a stimulus
380
+ takes;
381
+ * the topology and addresses, including a host whose routes collide with the
382
+ defaults;
383
+ * retries, and what a failed run blocks in their pipeline.
384
+
385
+ ---
386
+
278
387
  ## How It Works
279
388
 
280
389
  NSE orchestrates Linux kernel network subsystems and trace interfaces through a structured multi-stage execution pipeline:
@@ -372,7 +481,7 @@ Run static linting and unit tests:
372
481
  make verify
373
482
  ```
374
483
 
375
- Run full local CI verification (includes linting, unit tests, frontend build, docs build, PyPI smoke test, and privileged integration tests):
484
+ Run the full local CI pipeline (lint, type check, import boundaries, unit tests, docs build, and the release artifacts):
376
485
 
377
486
  ```bash
378
487
  make ci-local