network-sandbox-engine 2.0.0__tar.gz → 2.1.1__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 (46) hide show
  1. network_sandbox_engine-2.1.1/PKG-INFO +385 -0
  2. network_sandbox_engine-2.1.1/README.md +343 -0
  3. network_sandbox_engine-2.1.1/network_sandbox_engine.egg-info/PKG-INFO +385 -0
  4. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/SOURCES.txt +8 -0
  5. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/requires.txt +5 -5
  6. network_sandbox_engine-2.1.1/nse/__init__.py +20 -0
  7. network_sandbox_engine-2.1.1/nse/cli/runner.py +409 -0
  8. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/mock_listener.py +16 -6
  9. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/netns_controller.py +54 -45
  10. network_sandbox_engine-2.1.1/nse/core/paths.py +155 -0
  11. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/pipeline.py +210 -26
  12. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/rule_engine.py +7 -5
  13. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/scapy_injector.py +20 -10
  14. network_sandbox_engine-2.1.1/nse/core/trace_harvester.py +465 -0
  15. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/pyproject.toml +22 -10
  16. network_sandbox_engine-2.1.1/tests/test_docs_examples.py +74 -0
  17. network_sandbox_engine-2.1.1/tests/test_engine_internals.py +882 -0
  18. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/tests/test_netns.py +22 -18
  19. network_sandbox_engine-2.1.1/tests/test_oracle_e2e.py +170 -0
  20. network_sandbox_engine-2.1.1/tests/test_paths.py +302 -0
  21. network_sandbox_engine-2.1.1/tests/test_pipeline_unit.py +525 -0
  22. network_sandbox_engine-2.1.1/tests/test_runner_cli.py +195 -0
  23. network_sandbox_engine-2.1.1/tests/test_runner_logic.py +364 -0
  24. network_sandbox_engine-2.1.1/tests/test_trace_harvester.py +342 -0
  25. network_sandbox_engine-2.1.1/tests/test_trace_parser.py +199 -0
  26. network_sandbox_engine-2.0.0/PKG-INFO +0 -308
  27. network_sandbox_engine-2.0.0/README.md +0 -266
  28. network_sandbox_engine-2.0.0/network_sandbox_engine.egg-info/PKG-INFO +0 -308
  29. network_sandbox_engine-2.0.0/nse/__init__.py +0 -9
  30. network_sandbox_engine-2.0.0/nse/cli/runner.py +0 -194
  31. network_sandbox_engine-2.0.0/nse/core/trace_harvester.py +0 -224
  32. network_sandbox_engine-2.0.0/tests/test_oracle_e2e.py +0 -88
  33. network_sandbox_engine-2.0.0/tests/test_trace_parser.py +0 -51
  34. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/LICENSE +0 -0
  35. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/dependency_links.txt +0 -0
  36. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/entry_points.txt +0 -0
  37. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/top_level.txt +0 -0
  38. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/cli/__init__.py +0 -0
  39. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/__init__.py +0 -0
  40. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/naming.py +0 -0
  41. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/sniffer.py +0 -0
  42. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/utils.py +0 -0
  43. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/__init__.py +0 -0
  44. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/test_request.py +0 -0
  45. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/trace_event.py +0 -0
  46. {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/setup.cfg +0 -0
@@ -0,0 +1,385 @@
1
+ Metadata-Version: 2.4
2
+ Name: network-sandbox-engine
3
+ Version: 2.1.1
4
+ Summary: Headless Python engine for isolated network namespace testing and PCAP assertions.
5
+ Author: onyks
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/onyks-os/NetworkSandboxEngine
8
+ Project-URL: Repository, https://github.com/onyks-os/NetworkSandboxEngine
9
+ Project-URL: Issues, https://github.com/onyks-os/NetworkSandboxEngine/issues
10
+ Keywords: networking,namespace,testing,nftables,pcap,scapy
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: POSIX :: Linux
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: System :: Networking
19
+ Classifier: Topic :: Software Development :: Testing
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: scapy>=2.5.0
24
+ Requires-Dist: pydantic>=2.0.0
25
+ Provides-Extra: cli
26
+ Requires-Dist: pyyaml>=6.0; extra == "cli"
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
29
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
30
+ Requires-Dist: pyyaml>=6.0; extra == "dev"
31
+ Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
32
+ Requires-Dist: ruff; extra == "dev"
33
+ Requires-Dist: import-linter; extra == "dev"
34
+ Requires-Dist: mypy; extra == "dev"
35
+ Requires-Dist: mkdocs>=1.5.0; extra == "dev"
36
+ Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
37
+ Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
38
+ Requires-Dist: build>=1.0.0; extra == "dev"
39
+ Requires-Dist: twine>=7.0.0; extra == "dev"
40
+ Requires-Dist: pip-audit>=2.7.0; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ <!--
44
+ Copyright (c) 2026 onyks-os
45
+ SPDX-License-Identifier: MIT
46
+ -->
47
+
48
+ <h1 align="center">
49
+ Network Sandbox Engine (NSE)
50
+ </h1>
51
+
52
+ <h4 align="center">A Linux engine for deterministic <b>nftables firewall testing</b> inside isolated network namespaces.</h4>
53
+
54
+ <p align="center">
55
+ <img src="https://img.shields.io/badge/OS-Linux-blue?style=for-the-badge&logo=linux" alt="Linux">
56
+ <img src="https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge&logo=python" alt="Python">
57
+ <a href="https://github.com/onyks-os/NetworkSandboxEngine/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/onyks-os/NetworkSandboxEngine/ci.yml?style=for-the-badge&logo=github" alt="CI Status"></a>
58
+ <a href="https://onyks-os.github.io/nse/"><img src="https://img.shields.io/badge/docs-mkdocs-526CFE?style=for-the-badge&logo=materialformkdocs&logoColor=white" alt="Documentation"></a>
59
+ <a href="https://pypi.org/project/network-sandbox-engine/"><img src="https://img.shields.io/pypi/v/network-sandbox-engine?style=for-the-badge&logo=pypi" alt="PyPI"></a>
60
+ <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
61
+ </p>
62
+
63
+ <p align="center">
64
+ <a href="#why-nse">Why NSE?</a> •
65
+ <a href="#features">Features</a> •
66
+ <a href="#requirements">Requirements</a> •
67
+ <a href="#installation">Installation</a> •
68
+ <a href="#quickstart">Quickstart</a> •
69
+ <a href="#how-it-works">How It Works</a> •
70
+ <a href="#project-structure">Project Structure</a>
71
+ </p>
72
+
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
+ ## Why NSE?
82
+
83
+ 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.
84
+
85
+ Network Sandbox Engine (NSE) provides a safe, reproducible testing harness. It constructs ephemeral Linux network namespaces, wires virtual ethernet pairs, compiles `nftables` rulesets, and injects synthetic Layer 2 and Layer 3 packets using Scapy. All evaluation happens inside the sandbox namespace: host firewall state is never altered.
86
+
87
+ Key architectural properties:
88
+
89
+ * **Zero Host Mutation**: Rulesets are loaded exclusively into ephemeral sandbox namespaces (`nse_<uuid>`) and are completely removed during teardown.
90
+ * **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
+ * **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.
93
+
94
+ ### Requires root
95
+
96
+ NSE creates network namespaces, loads nftables rulesets and reads kernel trace
97
+ events, so it runs as root. It does not open a socket, a port or an RPC endpoint
98
+ of any kind — it is a library and a CLI that you invoke, and it holds privileges
99
+ only for the duration of a run.
100
+
101
+ Version 2.1.0 removed the FastAPI/Svelte web interface that earlier releases
102
+ shipped. That interface ran in-process as root from 2.0.0 onward, which was a
103
+ large attack surface for a testing tool; the code remains in the git history at
104
+ tag `v2.0.0` if you need it.
105
+
106
+ ---
107
+
108
+ ## The oracle contract
109
+
110
+ A firewall test is a negative assertion — *"this packet did not get through"* —
111
+ and a negative assertion is worth nothing unless the instrument is known to be
112
+ working. A trace monitor that never attached to the kernel and a firewall that
113
+ blocked everything produce byte-identical output.
114
+
115
+ NSE therefore refuses to report a verdict it cannot show it measured:
116
+
117
+ | Guarantee | Mechanism |
118
+ | :--- | :--- |
119
+ | The monitor was attached **before** the first test packet | A readiness canary is injected and re-injected until its kernel trace is observed. No observation, no run. |
120
+ | The monitor was **still** attached after the last one | A liveness canary runs after injection. If it is missed, the verdict stream is declared truncated. |
121
+ | The parser understood what the kernel said | Trace lines that no pattern matches are counted, and any count above zero is an error rather than a debug log. |
122
+ | The monitor did not die quietly | The read loop records *why* it ended — clean stop, unexpected EOF, timeout or crash — and only a clean stop is acceptable. |
123
+ | A missing verdict is not a pass | The CLI runner fails when the number of observed verdicts differs from the number expected, in either direction. |
124
+
125
+ Canary packets are excluded from results by trace id, so they never appear in
126
+ your verdict stream.
127
+
128
+ The suite proves this holds, rather than asserting it: `make test-blind` forces
129
+ the parser to understand nothing, and the build fails unless the runner exits
130
+ non-zero. That job runs in CI on every push.
131
+
132
+ ---
133
+
134
+ ## Features
135
+
136
+ * **In-Process Engine**: Direct Python API (`run_test_pipeline`) returning structured Pydantic models (`TestRequest`, `TraceEvent`).
137
+ * **Scapy Packet Injection**: Forge arbitrary TCP (with custom SYN, ACK, FIN, RST flags), UDP, ICMP, and ICMPv6 packets.
138
+ * **Isolated Topologies**:
139
+ * **Simple**: Single sandbox namespace (`nse_<id>`) wired directly to the host.
140
+ * **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%).
144
+
145
+ ---
146
+
147
+ ## Requirements
148
+
149
+ * **Linux OS** (Kernel 5.4 or later with network namespace and nftables support)
150
+ * **Python 3.10+**
151
+ * **nftables** (`nft`)
152
+ * **iproute2** (`ip`)
153
+ * **Root privileges** (required for `ip netns` and kernel trace operations)
154
+
155
+ On Debian or Ubuntu systems:
156
+
157
+ ```bash
158
+ sudo apt update && sudo apt install -y nftables iproute2 conntrack
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Installation
164
+
165
+ ### 1. PyPI Package (Recommended)
166
+
167
+ Install the core engine with CLI support:
168
+
169
+ ```bash
170
+ pip install "network-sandbox-engine[cli]"
171
+ ```
172
+
173
+ ### 2. Manual Source Install
174
+
175
+ For local development:
176
+
177
+ ```bash
178
+ git clone https://github.com/onyks-os/NetworkSandboxEngine.git
179
+ cd NetworkSandboxEngine
180
+ make setup
181
+ ```
182
+
183
+ ---
184
+
185
+ ## Quickstart
186
+
187
+ ### 1. Headless Python Library
188
+
189
+ ```python
190
+ import asyncio
191
+ from nse.core.netns_controller import NetnsController
192
+ from nse.core.pipeline import run_test_pipeline
193
+ from nse.models.test_request import TestRequest, PacketSpec
194
+
195
+ rules = """
196
+ table ip filter {
197
+ chain input {
198
+ type filter hook input priority 0; policy drop;
199
+ tcp dport 80 accept
200
+ }
201
+ }
202
+ """
203
+
204
+ request = TestRequest(
205
+ rules=rules,
206
+ packets=[
207
+ PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=80),
208
+ PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=22),
209
+ ],
210
+ )
211
+
212
+
213
+ async def main():
214
+ controller = NetnsController()
215
+ events = await run_test_pipeline(request=request, controller=controller)
216
+ for evt in events:
217
+ if evt.verdict:
218
+ print(f"[{evt.chain}] Verdict: {evt.verdict}")
219
+
220
+
221
+ asyncio.run(main())
222
+ ```
223
+
224
+ ### 2. YAML Test Suite Runner (CLI)
225
+
226
+ Create a test file `firewall_test.yaml`:
227
+
228
+ ```yaml
229
+ tests:
230
+ - name: "Allow HTTP Port 80, Drop SSH Port 22"
231
+ topology: simple
232
+ rules: |
233
+ table ip filter {
234
+ chain input {
235
+ type filter hook input priority 0; policy drop;
236
+ tcp dport 80 accept
237
+ }
238
+ }
239
+ packets:
240
+ - protocol: tcp
241
+ src_ip: 10.0.0.1
242
+ dst_ip: 10.0.0.2
243
+ dst_port: 80
244
+ expected_verdict: ACCEPT
245
+ - protocol: tcp
246
+ src_ip: 10.0.0.1
247
+ dst_ip: 10.0.0.2
248
+ dst_port: 22
249
+ expected_verdict: DROP
250
+ ```
251
+
252
+ `expected_verdict` is per packet. Unknown keys are rejected rather than
253
+ defaulted, so a typo fails the suite instead of quietly becoming an expectation
254
+ you never wrote.
255
+
256
+ Run the suite with root privileges:
257
+
258
+ ```bash
259
+ sudo nse-runner --file firewall_test.yaml
260
+ ```
261
+
262
+ Exit codes: `0` all packets matched; `1` a verdict was wrong **or** the engine
263
+ could not observe one. Oracle errors are reported separately from firewall
264
+ failures, because they mean the measurement broke, not the ruleset.
265
+
266
+ ### 3. In a container
267
+
268
+ ```bash
269
+ podman build -t nse .
270
+ podman run --rm --cap-add=NET_ADMIN --cap-add=NET_RAW \
271
+ -v "$PWD/firewall_test.yaml:/suite.yaml:ro" nse --file /suite.yaml
272
+ ```
273
+
274
+ Useful for pinning the nftables version your rules are tested against.
275
+
276
+ ---
277
+
278
+ ## How It Works
279
+
280
+ NSE orchestrates Linux kernel network subsystems and trace interfaces through a structured multi-stage execution pipeline:
281
+
282
+ ```mermaid
283
+ graph TD
284
+ subgraph Step1["1. Test Specification"]
285
+ Req["<b>TestRequest</b><br/>ruleset + packets + topology"]
286
+ end
287
+
288
+ subgraph Step2["2. Ephemeral Netns Sandbox"]
289
+ direction TB
290
+ Netns["<b>Netns Setup</b><br/>nse_&lt;id&gt; & veth links"]
291
+ RuleEng["<b>Rule Engine</b><br/>validate & load nftables"]
292
+ Inject["<b>Scapy Injector</b><br/>L2/L3 packet injection"]
293
+ NFT["<b>Kernel nftables</b><br/>meta nftrace set 1"]
294
+
295
+ Netns --> RuleEng
296
+ RuleEng --> Inject
297
+ Inject --> NFT
298
+ end
299
+
300
+ subgraph Step3["3. Trace Evaluation & Oracle"]
301
+ direction TB
302
+ Harvester["<b>Trace Harvester</b><br/>nft monitor trace stream"]
303
+ Oracle["<b>Deterministic Oracle</b><br/>TraceEvents & verdicts"]
304
+
305
+ Harvester --> Oracle
306
+ end
307
+
308
+ Step1 --> Step2
309
+ Step2 --> Step3
310
+ ```
311
+
312
+ 1. **Ruleset Validation**: `RuleEngine.validate()` dry-runs the ruleset using `nft --check -f`.
313
+ 2. **Sandbox Provisioning**: `NetnsController` creates the isolated network namespace and configures virtual ethernet (`veth`) interfaces.
314
+ 3. **Trace Initialization**: Rulesets are loaded into the namespace with kernel tracing armed (`meta nftrace set 1`).
315
+ 4. **Packet Injection**: `ScapyInjector` injects synthetic frames across the veth link.
316
+ 5. **Verdict Harvesting**: `TraceHarvester` captures `nft monitor trace` events and returns structured `TraceEvent` objects.
317
+ 6. **Teardown**: The namespace and all associated veth interfaces are automatically deleted.
318
+
319
+ For complete technical specifications, see the [Technical Architecture Guide](docs/ARCHITECTURE.md).
320
+
321
+ ---
322
+
323
+ ## Project Structure
324
+
325
+ ```text
326
+ NetworkSandboxEngine/
327
+ ├── nse/ # Core PyPI package (network-sandbox-engine)
328
+ │ ├── core/ # Kernel primitives, pipeline, and naming rules
329
+ │ ├── models/ # Pydantic models (TestRequest, PacketSpec, TraceEvent)
330
+ │ └── cli/ # Headless YAML runner entrypoint
331
+ ├── docs/ # Architecture specs and MkDocs web documentation
332
+ ├── tests/ # Unit, golden file, and privileged e2e tests
333
+ │ └── fixtures/nft_trace/ # Golden `nft monitor trace` corpus
334
+ ├── pyproject.toml # Build backend configuration
335
+ └── Makefile # Local automation and CI workflow
336
+ ```
337
+
338
+ ---
339
+
340
+ ## Releasing
341
+
342
+ One tag. `git push origin vX.Y.Z` builds, signs with Sigstore, publishes the
343
+ GitHub Release, uploads to TestPyPI, installs from TestPyPI and smoke-tests it,
344
+ and only then uploads to PyPI. Rehearse with `make release-dry`.
345
+
346
+ See [docs/RELEASING.md](docs/RELEASING.md).
347
+
348
+ ## Documentation
349
+
350
+ Full interactive web documentation is available at:
351
+ [https://onyks-os.github.io/nse/](https://onyks-os.github.io/nse/)
352
+
353
+ Build the documentation locally:
354
+
355
+ ```bash
356
+ make docs
357
+ ```
358
+
359
+ Serve the documentation with hot-reload on `http://127.0.0.1:8000`:
360
+
361
+ ```bash
362
+ make docs-serve
363
+ ```
364
+
365
+ ---
366
+
367
+ ## Testing & Local CI
368
+
369
+ Run static linting and unit tests:
370
+
371
+ ```bash
372
+ make verify
373
+ ```
374
+
375
+ Run full local CI verification (includes linting, unit tests, frontend build, docs build, PyPI smoke test, and privileged integration tests):
376
+
377
+ ```bash
378
+ make ci-local
379
+ ```
380
+
381
+ ---
382
+
383
+ ## License
384
+
385
+ This project is licensed under the [MIT License](LICENSE).