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.
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/PKG-INFO +126 -17
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/README.md +124 -16
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/PKG-INFO +126 -17
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/SOURCES.txt +28 -0
- network_sandbox_engine-2.2.0/nse/__init__.py +42 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/cli/runner.py +253 -79
- network_sandbox_engine-2.2.0/nse/core/async_work.py +39 -0
- network_sandbox_engine-2.2.0/nse/core/environment.py +66 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/mock_listener.py +80 -1
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/naming.py +8 -2
- network_sandbox_engine-2.2.0/nse/core/netns_controller.py +1066 -0
- network_sandbox_engine-2.2.0/nse/core/pipeline.py +693 -0
- network_sandbox_engine-2.2.0/nse/core/process.py +768 -0
- network_sandbox_engine-2.2.0/nse/core/resource_network.py +161 -0
- network_sandbox_engine-2.2.0/nse/core/resource_registry.py +365 -0
- network_sandbox_engine-2.2.0/nse/core/sniffer.py +779 -0
- network_sandbox_engine-2.2.0/nse/core/trace_attribution.py +61 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/trace_harvester.py +44 -4
- network_sandbox_engine-2.2.0/nse/core/verdicts.py +64 -0
- network_sandbox_engine-2.2.0/nse/models/artifacts.py +73 -0
- network_sandbox_engine-2.2.0/nse/models/capture_report.py +219 -0
- network_sandbox_engine-2.2.0/nse/models/experiment_report.py +266 -0
- network_sandbox_engine-2.2.0/nse/models/network_config.py +57 -0
- network_sandbox_engine-2.2.0/nse/models/process.py +271 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/test_request.py +17 -1
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/trace_event.py +9 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/pyproject.toml +2 -1
- network_sandbox_engine-2.2.0/tests/test_api_compat.py +179 -0
- network_sandbox_engine-2.2.0/tests/test_async_work.py +62 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_engine_internals.py +181 -28
- network_sandbox_engine-2.2.0/tests/test_examples.py +127 -0
- network_sandbox_engine-2.2.0/tests/test_exec_argv.py +177 -0
- network_sandbox_engine-2.2.0/tests/test_experiment_report.py +451 -0
- network_sandbox_engine-2.2.0/tests/test_experiment_report_integration.py +96 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_netns.py +26 -36
- network_sandbox_engine-2.2.0/tests/test_network_config.py +82 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_paths.py +82 -9
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_pipeline_unit.py +76 -27
- network_sandbox_engine-2.2.0/tests/test_process.py +842 -0
- network_sandbox_engine-2.2.0/tests/test_process_integration.py +248 -0
- network_sandbox_engine-2.2.0/tests/test_resource_lifecycle.py +263 -0
- network_sandbox_engine-2.2.0/tests/test_resource_ownership.py +538 -0
- network_sandbox_engine-2.2.0/tests/test_resource_registry.py +305 -0
- network_sandbox_engine-2.2.0/tests/test_runner_cli.py +478 -0
- network_sandbox_engine-2.2.0/tests/test_sniffer.py +972 -0
- network_sandbox_engine-2.2.0/tests/test_sniffer_integration.py +287 -0
- network_sandbox_engine-2.2.0/tests/test_topology_concurrency.py +336 -0
- network_sandbox_engine-2.2.0/tests/test_trace_attribution.py +118 -0
- network_sandbox_engine-2.1.1/nse/__init__.py +0 -20
- network_sandbox_engine-2.1.1/nse/core/netns_controller.py +0 -614
- network_sandbox_engine-2.1.1/nse/core/pipeline.py +0 -537
- network_sandbox_engine-2.1.1/nse/core/sniffer.py +0 -57
- network_sandbox_engine-2.1.1/tests/test_runner_cli.py +0 -195
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/LICENSE +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/dependency_links.txt +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/entry_points.txt +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/requires.txt +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/network_sandbox_engine.egg-info/top_level.txt +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/cli/__init__.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/__init__.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/paths.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/rule_engine.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/scapy_injector.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/core/utils.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/nse/models/__init__.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/setup.cfg +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_docs_examples.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_oracle_e2e.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_runner_logic.py +0 -0
- {network_sandbox_engine-2.1.1 → network_sandbox_engine-2.2.0}/tests/test_trace_harvester.py +0 -0
- {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.
|
|
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
|
-
<
|
|
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
|
-
* **
|
|
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
|
|
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
|
-
* **
|
|
142
|
-
* **
|
|
143
|
-
* **
|
|
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
|
|
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
|
-
<
|
|
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
|
-
* **
|
|
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
|
|
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
|
-
* **
|
|
100
|
-
* **
|
|
101
|
-
* **
|
|
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
|
|
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.
|
|
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
|
-
<
|
|
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
|
-
* **
|
|
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
|
|
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
|
-
* **
|
|
142
|
-
* **
|
|
143
|
-
* **
|
|
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
|
|
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
|