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.
- network_sandbox_engine-2.1.1/PKG-INFO +385 -0
- network_sandbox_engine-2.1.1/README.md +343 -0
- network_sandbox_engine-2.1.1/network_sandbox_engine.egg-info/PKG-INFO +385 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/SOURCES.txt +8 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/requires.txt +5 -5
- network_sandbox_engine-2.1.1/nse/__init__.py +20 -0
- network_sandbox_engine-2.1.1/nse/cli/runner.py +409 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/mock_listener.py +16 -6
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/netns_controller.py +54 -45
- network_sandbox_engine-2.1.1/nse/core/paths.py +155 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/pipeline.py +210 -26
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/rule_engine.py +7 -5
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/scapy_injector.py +20 -10
- network_sandbox_engine-2.1.1/nse/core/trace_harvester.py +465 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/pyproject.toml +22 -10
- network_sandbox_engine-2.1.1/tests/test_docs_examples.py +74 -0
- network_sandbox_engine-2.1.1/tests/test_engine_internals.py +882 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/tests/test_netns.py +22 -18
- network_sandbox_engine-2.1.1/tests/test_oracle_e2e.py +170 -0
- network_sandbox_engine-2.1.1/tests/test_paths.py +302 -0
- network_sandbox_engine-2.1.1/tests/test_pipeline_unit.py +525 -0
- network_sandbox_engine-2.1.1/tests/test_runner_cli.py +195 -0
- network_sandbox_engine-2.1.1/tests/test_runner_logic.py +364 -0
- network_sandbox_engine-2.1.1/tests/test_trace_harvester.py +342 -0
- network_sandbox_engine-2.1.1/tests/test_trace_parser.py +199 -0
- network_sandbox_engine-2.0.0/PKG-INFO +0 -308
- network_sandbox_engine-2.0.0/README.md +0 -266
- network_sandbox_engine-2.0.0/network_sandbox_engine.egg-info/PKG-INFO +0 -308
- network_sandbox_engine-2.0.0/nse/__init__.py +0 -9
- network_sandbox_engine-2.0.0/nse/cli/runner.py +0 -194
- network_sandbox_engine-2.0.0/nse/core/trace_harvester.py +0 -224
- network_sandbox_engine-2.0.0/tests/test_oracle_e2e.py +0 -88
- network_sandbox_engine-2.0.0/tests/test_trace_parser.py +0 -51
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/LICENSE +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/dependency_links.txt +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/entry_points.txt +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/network_sandbox_engine.egg-info/top_level.txt +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/cli/__init__.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/__init__.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/naming.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/sniffer.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/core/utils.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/__init__.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/test_request.py +0 -0
- {network_sandbox_engine-2.0.0 → network_sandbox_engine-2.1.1}/nse/models/trace_event.py +0 -0
- {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_<id> & 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).
|