network-sandbox-engine 1.0.0__py3-none-any.whl

network_sandbox_engine-1.0.0.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: network-sandbox-engine
+Version: 1.0.0
+Summary: Headless Python engine for isolated network namespace testing and PCAP assertions.
+Author: onyks
+License: MIT
+Project-URL: Homepage, https://github.com/onyks-os/NetworkSandboxEngine
+Project-URL: Repository, https://github.com/onyks-os/NetworkSandboxEngine
+Project-URL: Issues, https://github.com/onyks-os/NetworkSandboxEngine/issues
+Keywords: networking,namespace,testing,nftables,pcap,scapy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scapy>=2.5.0
+Provides-Extra: cli
+Requires-Dist: pydantic>=2.0.0; extra == "cli"
+Requires-Dist: pyyaml>=6.0; extra == "cli"
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.111.0; extra == "gui"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "gui"
+Requires-Dist: websockets>=12.0; extra == "gui"
+Requires-Dist: pydantic>=2.0.0; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Network Sandbox Engine (NSE)
+
+A headless Python engine for deterministic, kernel-level `nftables` firewall testing, with an optional Svelte/FastAPI web GUI.
+
+[![PyPI](https://img.shields.io/badge/PyPI-network--sandbox--engine-blue)](https://pypi.org/project/network-sandbox-engine/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Linux only](https://img.shields.io/badge/OS-Linux%20only-lightgrey.svg)](https://kernel.org/)
+
+NSE uses ephemeral Linux network namespaces and Scapy to validate firewall logic. Rules are executed by the actual kernel: no userspace simulation, no host pollution.
+
+---
+
+## How It Works
+
+```text
+ [Library / CLI]            [FastAPI Daemon (optional)]     [Sandbox - Linux netns]
+        |                              |                              |
+        |-- run_test_pipeline() ------>|                              |
+        |   (rules + packet sequence)  |-- 1. Create topology ------->| (veth pair / gateway)
+        |                              |-- 2. Spawn mock listeners -->| (TCP/UDP echo daemons)
+        |                              |-- 3. Load nft rules -------->|
+        |                              |-- 4. Start nft monitor ----->| (trace harvester)
+        |                              |-- 5. Inject packets -------->| (Scapy L2/L3)
+        |                              |<- 6. Poll conntrack ---------| (/proc/net/nf_conntrack)
+        |<-- TraceEvent stream --------|-- 7. Stream verdicts ------->| (WebSocket or iterator)
+        |                              |-- 8. Teardown (GC) --------->| (namespace deleted)
+```
+
+The host firewall is never modified. Rules are confined to the isolated sandbox namespace and are destroyed with it at teardown.
+
+---
+
+## Architecture Overview
+
+| Component              | Technology               | Description                                                                   |
+| ---------------------- | ------------------------ | ----------------------------------------------------------------------------- |
+| Headless Core          | Python 3.10+ / Scapy     | `NetnsController`, `PCAPAsserter`, `RuleEngine`, `ScapyInjector`, `Pipeline`  |
+| CLI Test Runner        | `nse-runner` / YAML      | Headless YAML test suite runner for CI/CD pipelines                           |
+| GUI Daemon (optional)  | FastAPI + Uvicorn        | REST and WebSocket API streaming `TraceEvent` objects from the kernel         |
+| Frontend (optional)    | Svelte + Vite            | Rule editor, multi-packet crafter, animated trace visualizer, conntrack table |
+| Packet Injection       | Scapy (Layer 2/3)        | IPv4 and IPv6, TCP with custom flags, UDP, ICMP, ICMPv6                       |
+| Mock Listeners         | TCP/UDP echo sockets     | Background listeners inside namespaces to complete handshakes                 |
+| Conntrack Engine       | `/proc/net/nf_conntrack` | Captures `ESTABLISHED`, `SYN_SENT`, `TIME_WAIT` states in real-time          |
+
+---
+
+## Prerequisites
+
+NSE requires Linux with kernel 5.4 or later (namespace and nftables trace support).
+
+| Dependency        | Purpose                                    |
+| ----------------- | ------------------------------------------ |
+| Python 3.10+      | Core library, CLI, and optional GUI daemon |
+| nftables (`nft`)  | Compiles rules and generates trace events  |
+| iproute2 (`ip`)   | Manages network namespaces and veth pairs  |
+| conntrack         | Reads connection state from kernel tables  |
+| Node.js 18+       | Required only to build the Svelte frontend |
+
+```bash
+# Debian / Ubuntu
+sudo apt install nftables iproute2 python3-venv python3-pip conntrack
+```
+
+---
+
+## Quickstart
+
+### A. Headless library
+
+```bash
+pip install network-sandbox-engine
+```
+
+```python
+import asyncio
+from nse.core.pipeline import run_test_pipeline
+from nse.models.test_request import PacketSpec, TestRequest
+
+async def main():
+    req = TestRequest(
+        rules="table ip filter { chain input { type filter hook input priority 0; tcp dport 22 accept; drop; } }",
+        packets=[PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=22)],
+    )
+    events = await run_test_pipeline(req)
+    for ev in events:
+        print(ev)
+
+asyncio.run(main())
+```
+
+### B. CLI YAML runner
+
+```bash
+pip install "network-sandbox-engine[cli]"
+nse-runner --file my_tests.yaml
+```
+
+```yaml
+# my_tests.yaml
+- name: SSH accepted
+  rules: |
+    table ip filter {
+      chain input { type filter hook input priority 0; tcp dport 22 accept; drop; }
+    }
+  packets:
+    - protocol: tcp
+      src_ip: 10.0.0.1
+      dst_ip: 10.0.0.2
+      dst_port: 22
+  expect:
+    verdict: ACCEPT
+```
+
+### C. Full GUI (development mode)
+
+```bash
+git clone https://github.com/onyks-os/NetworkSandboxEngine.git
+cd NetworkSandboxEngine
+make setup     # bootstrap venv + npm install
+make backend   # starts FastAPI daemon (requires sudo -E)
+make frontend  # starts Vite dev server on port 5173
+```
+
+Open `http://localhost:5173` in a browser.
+
+---
+
+## Repository Layout
+
+```
+NetworkSandboxEngine/
+|-- nse/                        # PyPI package (pip install network-sandbox-engine)
+|   |-- __init__.py             # Public API: NetnsController, PCAPAsserter
+|   |-- core/                   # Kernel-level primitives
+|   |   |-- netns_controller.py
+|   |   |-- scapy_injector.py
+|   |   |-- sniffer.py          # PCAPAsserter
+|   |   |-- pipeline.py         # run_test_pipeline()
+|   |   `-- rule_engine.py      # nft load / validate
+|   |-- models/                 # Pydantic models (lazy import via try/except)
+|   |   |-- test_request.py     # PacketSpec, TestRequest, TopologyType
+|   |   `-- trace_event.py      # TraceEvent
+|   `-- cli/
+|       `-- runner.py           # nse-runner entrypoint
+|
+|-- gui/                        # Not on PyPI - GUI daemon only
+|   |-- server.py               # FastAPI + Uvicorn entrypoint
+|   |-- api/                    # REST routes and WebSocket
+|   `-- daemon/                 # trace_harvester, mock_listener
+|       `-- gui_svelte/         # Svelte + Vite frontend
+|
+|-- tests/
+|   `-- test_netns.py           # 20 unit tests (2 skipped without root)
+|
+|-- pyproject.toml              # Build config - packages only nse/
+|-- Makefile                    # make setup | test | lint | release
+`-- conftest.py                 # Root sys.path for pytest
+```
+
+---
+
+## Key Features
+
+### 1. Stateful Packet Sequences and Conntrack
+
+Ordered lists of packets simulate TCP flows. NSE polls `/proc/net/nf_conntrack` and streams live connection states (`SYN_SENT`, `ESTABLISHED`, `TIME_WAIT`) after each injection.
+
+### 2. Automatic Mock Listeners
+
+Destination ports in incoming packets receive a background echo listener spawned inside the namespace, completing TCP handshakes and generating valid conntrack entries without manual setup.
+
+### 3. Gateway Routing Topology
+
+The Gateway Topology spawns a three-namespace chain: Host - Router - Server. Rules are loaded into the Router namespace to test `forward` chain hooks, routing decisions, and NAT.
+
+### 4. Dual-Stack IPv4 and IPv6
+
+ICMPv6 echo, dual-stack veth links, and DAD disabled for instant address availability inside namespaces.
+
+### 5. PCAP Assertions
+
+`PCAPAsserter` wraps Scapy's `AsyncSniffer` to arm a BPF filter on a veth interface and assert captured packets. It is usable independently of the full pipeline.
+
+---
+
+## Testing
+
+Unit tests (no root required):
+
+```bash
+make test
+# 20 passed, 2 skipped (root-only integration tests)
+```
+
+Integration tests (root required):
+
+```bash
+sudo -E .venv/bin/pytest tests/ -v
+```
+
+CLI test suite (root required):
+
+```bash
+sudo -E .venv/bin/python -m nse.cli.runner --file tests/fixtures/test_suite.yaml
+```
+
+---
+
+## Production Deployment
+
+### Package Extras
+
+| Mode           | Install command                             | Dependencies           |
+| :------------- | :------------------------------------------ | :--------------------- |
+| Headless core  | `pip install network-sandbox-engine`        | `scapy`                |
+| With CLI runner | `pip install "network-sandbox-engine[cli]"` | + `pydantic`, `pyyaml` |
+
+The GUI daemon is not distributed via PyPI. It is run from a repository clone.
+
+### Building Release Artifacts
+
+```bash
+make release
+```
+
+This target performs the following steps:
+
+1. Runs `make lint` and `make test`; fails on any error.
+2. Builds `.whl` and `.tar.gz` with `python -m build`.
+3. Copies `Dockerfile` and `scripts/nse.service` into `release/`.
+4. Generates `SHA256SUMS`.
+5. Signs `SHA256SUMS` with GPG, producing `SHA256SUMS.asc`. The signing key is auto-detected from the keyring; it can be overridden with `GPG_KEY_ID=<id>`.
+
+Output in `release/`:
+
+```
+release/
+|-- network_sandbox_engine-1.0.0-py3-none-any.whl
+|-- network_sandbox_engine-1.0.0.tar.gz
+|-- Dockerfile
+|-- nse.service
+|-- SHA256SUMS
+`-- SHA256SUMS.asc
+```
+
+### Native Installation with Systemd
+
+```bash
+sudo pip install release/network_sandbox_engine-1.0.0-py3-none-any.whl
+sudo cp release/nse.service /etc/systemd/system/
+sudo systemctl daemon-reload && sudo systemctl enable --now nse
+```
+
+### Docker
+
+```bash
+docker build -t nse -f release/Dockerfile .
+docker run --privileged -p 8000:8000 -d --name nse-container nse
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

network_sandbox_engine-1.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+network_sandbox_engine-1.0.0.dist-info/licenses/LICENSE,sha256=MFgt8rXwHCDn0xZdKsvrmoJsAmsJKBjGxTe5fnQ5-4M,1062
+nse/__init__.py,sha256=H0PH7qnBwXSWXwZ2bKU9YaGQFnLK6ARw8pj74w_DLvE,137
+nse/cli/__init__.py,sha256=xyEcaP29dx62zL_d7kjMfPHYou87DFwTk9z2F_TvWE0,22
+nse/cli/runner.py,sha256=knMPgE_M27no3xIlz6FOdKq7vF2oFiFLPsMr753iT9w,6983
+nse/core/__init__.py,sha256=Lq5e7p4Lis3O8SnVdZaPohvkjqpblAKxzJWJAtSPWew,44
+nse/core/netns_controller.py,sha256=WW2WUuCup6l8gTWjDXU1i6rXi-C5vUYpo9BgOyNxDMg,18027
+nse/core/pipeline.py,sha256=gQyG5F6HV43iCUdIYrAblp1KEfkQPMdjFz822DGnjbw,13603
+nse/core/rule_engine.py,sha256=gcxYVFctN4vII6r3ZrHhmjDenzTJeQrEkMT-vjwwzY4,3711
+nse/core/scapy_injector.py,sha256=oaLpAfw8w2Wz-wqAzVxbgM_aQWYYDrJwB9XHIqLu0AQ,7176
+nse/core/sniffer.py,sha256=72aNoThXEwZViF8L1zF91GiohFaMyfLE-k13n6cA19M,1795
+nse/models/__init__.py,sha256=dGqvI1YHvLMN2m3sbgNPfBfoE1b-6MBW3KsneeYVS8k,26
+nse/models/base.py,sha256=0jr73qvrufmdf5l2Lx4-LGdD_7BJkOfmePxTMAdvBjg,534
+nse/models/test_request.py,sha256=4QcRqucFlLHpR5CCS_5pw-UCygDGoZKDnLBhgUY7rSU,3267
+nse/models/trace_event.py,sha256=vzQ4psGzVTIuaib4rQ2rqA2AWomRhczLw2VKEmkU4kw,2841
+network_sandbox_engine-1.0.0.dist-info/METADATA,sha256=AX8Q8Xc56EiI0GN2G3xZ1HNFnddMbEhzOupBbIcjNUc,10951
+network_sandbox_engine-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+network_sandbox_engine-1.0.0.dist-info/entry_points.txt,sha256=oLI3KtSjK-M8oiKbjBP67ixM4zgMb3dFJMc43pDNDKc,51
+network_sandbox_engine-1.0.0.dist-info/top_level.txt,sha256=i3PM6tEhBAFaw7b_fn1zZy-njycoweG8M9byGRjVocw,4
+network_sandbox_engine-1.0.0.dist-info/RECORD,,

network_sandbox_engine-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

network_sandbox_engine-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nse-runner = nse.cli.runner:main

network_sandbox_engine-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onyks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

network_sandbox_engine-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nse

nse/__init__.py

@@ -0,0 +1,4 @@
+from .core.netns_controller import NetnsController
+from .core.sniffer import PCAPAsserter
+
+__all__ = ["NetnsController", "PCAPAsserter"]

nse/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI subpackage."""

nse/cli/runner.py

@@ -0,0 +1,218 @@
+import sys
+import argparse
+import time
+import asyncio
+
+try:
+    import yaml
+    from pydantic import ValidationError
+    from nse.models.test_request import TestRequest, PacketSpec, TopologyType
+    from nse.models.trace_event import TraceEvent
+    from nse.core.netns_controller import NetnsController, TestRun
+    from nse.core.pipeline import run_test_pipeline
+except ImportError:
+    yaml = None
+    ValidationError = None
+    TestRequest = None
+    PacketSpec = None
+    TopologyType = None
+    TraceEvent = None
+    NetnsController = None
+    TestRun = None
+    run_test_pipeline = None
+
+
+def check_cli_dependencies() -> None:
+    """Verify that CLI extras are installed."""
+    if yaml is None or ValidationError is None or TestRequest is None:
+        print("[FATAL ERROR] Missing dependencies for CLI runner.", file=sys.stderr)
+        print("To use the YAML test runner, install the CLI extras:", file=sys.stderr)
+        print("    pip install 'network-sandbox-engine[cli]'", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    check_cli_dependencies()
+    import logging
+
+    logging.basicConfig(
+        level=logging.DEBUG, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", force=True
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="nse-runner",
+        description="Network Sandbox Engine YAML/JSON test runner",
+    )
+    parser.add_argument(
+        "--file",
+        required=True,
+        help="Path to the test suite YAML or JSON file",
+    )
+
+    args = parser.parse_args()
+
+    print(f"[NSE] Loading test suite from: {args.file}")
+    try:
+        with open(args.file, "r") as f:
+            if args.file.endswith(".json"):
+                import json
+
+                data = json.load(f)
+            else:
+                data = yaml.safe_load(f)
+    except Exception as e:
+        print(f"Error reading test suite file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    test_cases = data.get("tests", [])
+    if not test_cases:
+        print("No test cases found in suite.", file=sys.stderr)
+        sys.exit(0)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    controller = NetnsController()
+
+    passed = 0
+    failed = 0
+
+    print(f"Found {len(test_cases)} test cases.")
+    print("-" * 60)
+
+    for tc_idx, tc in enumerate(test_cases):
+        name = tc.get("name", f"Test case {tc_idx + 1}")
+        print(f"Running test: {name}...")
+
+        topology_str = tc.get("topology", "simple").lower()
+        topology = TopologyType.GATEWAY if topology_str == "gateway" else TopologyType.SIMPLE
+
+        rules = tc.get("rules", "")
+
+        packets_data = tc.get("packets", [])
+        packets = []
+        expected_verdicts = []
+
+        for p in packets_data:
+            expected_verdicts.append(p.get("expected_verdict", "ACCEPT").upper())
+
+            protocol = p.get("protocol", "tcp")
+            src_ip = p.get("src_ip", "10.0.1.1" if topology == TopologyType.GATEWAY else "10.0.0.1")
+            dst_ip = p.get("dst_ip", "10.0.2.2" if topology == TopologyType.GATEWAY else "10.0.0.2")
+            src_port = p.get("src_port")
+            dst_port = p.get("dst_port")
+            tcp_flags = p.get("tcp_flags", [])
+
+            packets.append(
+                PacketSpec(
+                    protocol=protocol,
+                    src_ip=src_ip,
+                    dst_ip=dst_ip,
+                    src_port=src_port,
+                    dst_port=dst_port,
+                    tcp_flags=tcp_flags,
+                )
+            )
+
+        try:
+            request = TestRequest(rules=rules, packets=packets, topology=topology)
+        except ValidationError as e:
+            print(f"  [FAIL] Test request validation failed:\n{e}")
+            failed += 1
+            continue
+
+        test_id = f"cli_{tc_idx}_{int(time.time())}"
+        run = TestRun(test_id=test_id, netns_name=f"nse_{test_id}", request=request)
+
+        try:
+            loop.run_until_complete(run_test_pipeline(controller, run))
+        except Exception as e:
+            print(f"  [FAIL] Pipeline crashed with error: {e}")
+            failed += 1
+            continue
+
+        events = []
+        while not run.event_queue.empty():
+            evt = loop.run_until_complete(run.event_queue.get())
+            if evt is None:
+                continue
+            events.append(evt)
+
+        trace_id_to_verdicts = {}
+        trace_id_to_hook = {}
+        all_seen_trace_ids = []
+        errors = []
+
+        for evt in events:
+            if evt.type == "error":
+                errors.append(evt.raw_message)
+            elif evt.trace_id:
+                if evt.trace_id not in trace_id_to_verdicts:
+                    trace_id_to_verdicts[evt.trace_id] = []
+                    all_seen_trace_ids.append(evt.trace_id)
+
+                if evt.type == "hook" and evt.hook:
+                    if evt.trace_id not in trace_id_to_hook:
+                        trace_id_to_hook[evt.trace_id] = evt.hook
+
+                if evt.verdict:
+                    trace_id_to_verdicts[evt.trace_id].append(evt.verdict.upper())
+
+        if errors:
+            print(f"  [FAIL] Test encountered errors: {', '.join(errors)}")
+            failed += 1
+            continue
+
+        # Keep only trace IDs that enter on the expected injection hook interface
+        ordered_trace_ids = []
+        for tid in all_seen_trace_ids:
+            hook = trace_id_to_hook.get(tid, "")
+            is_valid = False
+            if topology == TopologyType.GATEWAY:
+                if hook.startswith("vrh-") or hook == "veth-nse":
+                    is_valid = True
+            else:
+                if hook == "veth-nse":
+                    is_valid = True
+
+            if is_valid:
+                ordered_trace_ids.append(tid)
+
+        actual_verdicts = []
+        for tid in ordered_trace_ids:
+            v_list = trace_id_to_verdicts[tid]
+            if any(v in ("DROP", "REJECT") for v in v_list):
+                actual_verdicts.append("DROP")
+            elif any(v == "ACCEPT" for v in v_list):
+                actual_verdicts.append("ACCEPT")
+            else:
+                actual_verdicts.append("DROP")
+
+        while len(actual_verdicts) < len(expected_verdicts):
+            actual_verdicts.append("DROP")
+
+        test_passed = True
+        for idx, (exp, act) in enumerate(zip(expected_verdicts, actual_verdicts)):
+            if exp != act:
+                print(f"  [FAIL] Packet {idx + 1}: expected {exp}, got {act}")
+                test_passed = False
+            else:
+                print(f"  [OK] Packet {idx + 1}: expected {exp}, got {act}")
+
+        if test_passed:
+            print(f"  => SUCCESS: {name}")
+            passed += 1
+        else:
+            print(f"  => FAILURE: {name}")
+            failed += 1
+
+    print("-" * 60)
+    print(f"Test Suite Summary: {passed} passed, {failed} failed.")
+    if failed > 0:
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

nse/core/__init__.py

@@ -0,0 +1 @@
+"""Core network sandbox engine features."""