onyks-os/NetworkSandboxEngine
GitHub: onyks-os/NetworkSandboxEngine
一个基于 Linux network namespace 和 Scapy 的 nftables 防火墙规则测试沙箱，提供无头 CI 测试与可视化追踪两种模式。
Stars: 0 | Forks: 0
# 网络 Sandbox 引擎 (NSE)
一个无头模式的 Python 引擎，用于确定性的内核级 `nftables` 防火墙测试，并带有可选的 Svelte/FastAPI Web GUI。
[](https://pypi.org/project/network-sandbox-engine/)
[](https://www.python.org/)
[](LICENSE)
[](https://kernel.org/)
NSE 使用临时的 Linux network namespace 和 Scapy 来验证防火墙逻辑。规则由实际内核执行：没有用户空间模拟，也不会污染宿主机。
## 工作原理
```
[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)
```
宿主机防火墙永远不会被修改。规则被限制在隔离的沙箱 namespace 中，并会在销毁时随之一起销毁。
## 架构概述
| 组件 | 技术 | 描述 |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------ |
| 无头模式核心 | Python 3.10+ / Scapy | `NetnsController`、`PCAPAsserter`、`RuleEngine`、`ScapyInjector`、`Pipeline` |
| CLI 测试运行器 | `nse-runner` / YAML | 用于 CI/CD pipeline 的无头模式 YAML 测试套件运行器 |
| GUI 守护进程（可选） | FastAPI + Uvicorn | REST 和 WebSocket API，流式传输来自内核的 `TraceEvent` 对象 |
| 前端（可选） | Svelte + Vite | 规则编辑器、多数据包生成器、动画追踪可视化工具、conntrack 表 |
| 数据包注入 | Scapy (Layer 2/3) | IPv4 和 IPv6、带自定义 flag 的 TCP、UDP、ICMP、ICMPv6 |
| 模拟监听器 | TCP/UDP echo socket | namespace 内的后台监听器，用于完成握手 |
| Conntrack 引擎 | `/proc/net/nf_conntrack` | 实时捕获 `ESTABLISHED`、`SYN_SENT`、`TIME_WAIT` 状态 |
## 前置条件
NSE 要求使用内核版本 5.4 或更高版本的 Linux（支持 namespace 和 nftables trace）。
| 依赖项 | 用途 |
| ----------------- | --------------------------------------------- |
| Python 3.10+ | 核心库、CLI 以及可选的 GUI 守护进程 |
| nftables (`nft`) | 编译规则并生成 trace 事件 |
| iproute2 (`ip`) | 管理 network namespace 和 veth 对 |
| conntrack | 从内核表读取连接状态 |
| Node.js 18+ | 仅在构建 Svelte 前端时需要 |
```
# Debian / Ubuntu
sudo apt install nftables iproute2 python3-venv python3-pip conntrack
```
## 快速开始
### A. 无头模式库
```
pip install network-sandbox-engine
```
```
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 运行器
```
pip install "network-sandbox-engine[cli]"
nse-runner --file my_tests.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. 完整 GUI（开发模式）
```
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
```
在浏览器中打开 `http://localhost:5173`。
## 仓库结构
```
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
```
## 核心功能
### 1. 有状态数据包序列与 Conntrack
有序的数据包列表用于模拟 TCP 流。NSE 轮询 `/proc/net/nf_conntrack`，并在每次注入后流式传输实时的连接状态（`SYN_SENT`、`ESTABLISHED`、`TIME_WAIT`）。
### 2. 自动化模拟监听器
传入数据包的目标端口会在 namespace 内启动一个后台 echo 监听器，无需手动设置即可完成 TCP 握手并生成有效的 conntrack 条目。
### 3. 网关路由拓扑
网关拓扑会生成一个包含三个 namespace 的链：Host - Router - Server。规则被加载到 Router namespace 中，以测试 `forward` 链 hook、路由决策以及 NAT。
### 4. 双栈 IPv4 与 IPv6
支持 ICMPv6 echo、双栈 veth 链接，并禁用 DAD 以实现 namespace 内的即时地址可用性。
### 5. PCAP 断言
`PCAPAsserter` 封装了 Scapy 的 `AsyncSniffer`，用于在 veth 接口上启用 BPF 过滤器并对捕获的数据包进行断言。它可以独立于完整 pipeline 使用。
## 测试
单元测试（无需 root 权限）：
```
make test
# 20 个通过，2 个跳过（仅 root 的 integration tests）
```
集成测试（需要 root 权限）：
```
sudo -E .venv/bin/pytest tests/ -v
```
CLI 测试套件（需要 root 权限）：
```
sudo -E .venv/bin/python -m nse.cli.runner --file tests/fixtures/test_suite.yaml
```
## 生产环境部署
### 扩展包
| 模式 | 安装命令 | 依赖项 |
| :------------- | :------------------------------------------ | :--------------------- |
| 无头模式核心 | `pip install network-sandbox-engine` | `scapy` |
| 带 CLI 运行器 | `pip install "network-sandbox-engine[cli]"` | + `pydantic`, `pyyaml` |
GUI 守护进程不通过 PyPI 发布。它是从克隆的代码仓库中运行的。
### 构建发布产物
```
make release
```
该目标执行以下步骤：
1. 运行 `make lint` 和 `make test`；遇到任何错误即失败。
2. 使用 `python -m build` 构建 `.whl` 和 `.tar.gz`。
3. 将 `Dockerfile` 和 `scripts/nse.service` 复制到 `release/`。
4. 生成 `SHA256SUMS`。
5. 使用 GPG 对 `SHA256SUMS` 进行签名，生成 `SHA256SUMS.asc`。签名密钥会从密钥环中自动检测；也可以使用 `GPG_KEY_ID=` 进行覆盖。
`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
```
### 使用 Systemd 进行本地安装
```
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
```
docker build -t nse -f release/Dockerfile .
docker run --privileged -p 8000:8000 -d --name nse-container nse
```
## 许可证
MIT。详见 [LICENSE](LICENSE)。
标签：AV绕过, certspotter, FastAPI, Linux网络命名空间, nftables, SBOM分析, Scapy, Svelte, 网络沙箱, 网络测试, 请求拦截, 逆向工具, 防火墙测试