为什么选择 NSE? • Oracle 契约 • 线上断言 • 功能特性 • 环境要求 • 安装 • 快速开始 • 工作原理 • 项目结构
在运行中的 Linux 系统上测试防火墙规则集存在重大风险:格式错误的规则可能会中断 SSH 管理会话、在测试期间泄露明文流量,或在主机上留下孤立的防火墙表。
Network Sandbox Engine (NSE) 提供了一个安全、可复现的测试框架。它构建临时的 Linux 网络命名空间、连接虚拟以太网对、编译 nftables 规则集,并使用 Scapy 注入合成的二层和三层数据包。所有评估都在沙箱命名空间内进行:主机防火墙状态绝不会被改动。
关键架构特性:
nse_<uuid>)中,并在拆除时被完全移除。nse/ 约 1200 条语句,测试覆盖率达 98%。NSE 会创建网络命名空间、加载 nftables 规则集并读取内核跟踪事件,因此以 root 身份运行。它不会打开任何类型的套接字、端口或 RPC 端点——它是一个由你调用的库和 CLI,并且仅在运行期间持有特权。
2.1.0 版本移除了早期版本附带的 FastAPI/Svelte Web 界面。该界面从 2.0.0 起以 root 身份在进程内运行,对于测试工具而言是巨大的攻击面;如果你需要,代码仍保留在 git 历史中的 v2.0.0 标签处。
防火墙测试是一种否定性断言——“这个数据包没有通过”——而除非已知测量工具正常工作,否则否定性断言毫无价值。一个从未附加到内核的跟踪监视器和一个阻止了一切流量的防火墙会产生逐字节相同的输出。
因此,NSE 拒绝报告它无法证明其已测量的判定结果:
| 保证 | 机制 |
|---|---|
| 监控器在第一个测试数据包之前就已挂载 | 注入一个就绪金丝雀数据包,并反复重新注入,直到观察到其内核跟踪记录。没有观察到,就不运行。 |
| 监控器在最后一个数据包之后仍然处于挂载状态 | 在注入完成后运行一个存活金丝雀数据包。如果它被遗漏,则判定结果流被声明为截断。 |
| 解析器理解了内核所表达的内容 | 统计没有任何模式匹配的跟踪行,任何大于零的计数都是错误,而不是调试日志。 |
| 监控器没有悄然终止 | 读取循环会记录它为什么结束——正常停止、意外 EOF、超时或崩溃——只有正常停止才是可接受的。 |
| 缺失的判定结果不算通过 | 当观察到的判定结果数量与预期数量不一致时(无论哪个方向),CLI 运行器都会失败。 |
金丝雀数据包会按跟踪 id 从结果中排除,因此它们绝不会出现在你的判定结果流中。
该测试套件证明这一点成立,而不是仅仅断言它:make test-blind 强制解析器什么都理解不了,除非运行器以非零状态退出,否则构建就会失败。该任务在每次推送时都会在 CI 中运行。
nft monitor trace 报告的是规则集决定了什么。它无法报告从规则集从未匹配过的接口上离开的内容,而这正是零泄漏声明实际要问的问题。PCAPAsserter 覆盖了这一点:一个 AsyncSniffer 包装器,在指定接口上捕获并将帧返回,因此测试可以断言某个激励产生了零个数据包。
from nse import PCAPAsserter
asserter = PCAPAsserter(iface="veth-host")
await asserter.start()
# ... send the stimulus ...
leaked = await asserter.stop()
assert not leaked, leaked
追踪 oracle 的规则同样适用,且需由调用方来执行:一个从未挂接的嗅探器和一个拦截了所有流量的防火墙都会返回空列表。在清空规则集的情况下捕获一次激励,并要求在断言其不存在之前先看到该帧。
默认过滤器仅抑制链路本地噪声,除此之外别无其他。 DEFAULT_FILTER 排除 ARP 和 ICMPv6 类型 133-137——即邻居发现(Neighbour Discovery),其携带的跳数限制为 255,无法到达远程观察者。其余所有内容均被捕获,包括发往全局可路由地址的 ICMPv6 echo。filter 参数会与该默认值合并;replace_default_filter=True 则仅使用你提供的过滤器。之所以存在这个逃生通道,是因为过滤器被编译进 BPF 并在内核中求值:被它排除的数据包永远不会到达用户空间,因此下游的任何消费者都无法恢复它。在 2.1.2 之前,默认值为 not arp and not icmp6,这同样会丢弃可路由的 ICMPv6——参见 issue #14。
run_test_pipeline),返回结构化的 Pydantic 模型(TestRequest、TraceEvent)。nse_<id>)直接连接到主机。nse_router_<id>)与服务器(nse_server_<id>)链式结构,用于转发和 NAT 测试。PCAPAsserter 在指定接口上捕获,使测试能够断言某次激励完全没有产生任何帧。参见在线路上进行断言。nse-runner)。在判定错误以及未能观察到判定结果时均以非零状态退出。mypy --strict)、架构边界强制(import-linter)、ruff 格式化,以及覆盖率棘轮(make coverage,下限 98%)。nft)ip)ip netns 和内核追踪操作所需)在 Debian 或 Ubuntu 系统上:
sudo apt update && sudo apt install -y nftables iproute2 conntrack
安装带 CLI 支持的核心引擎:
pip install "network-sandbox-engine[cli]"
用于本地开发:
git clone https://github.com/onyks-os/NetworkSandboxEngine.git
cd NetworkSandboxEngine
make setup
import asyncio
from nse.core.netns_controller import NetnsController
from nse.core.pipeline import run_test_pipeline
from nse.models.test_request import TestRequest, PacketSpec
rules = """
table ip filter {
chain input {
type filter hook input priority 0; policy drop;
tcp dport 80 accept
}
}
"""
request = TestRequest(
rules=rules,
packets=[
PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=80),
PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=22),
],
)
async def main():
controller = NetnsController()
events = await run_test_pipeline(request=request, controller=controller)
for evt in events:
if evt.verdict:
print(f"[{evt.chain}] Verdict: {evt.verdict}")
asyncio.run(main())
创建测试文件 firewall_test.yaml:
tests:
- name: "Allow HTTP Port 80, Drop SSH Port 22"
topology: simple
rules: |
table ip filter {
chain input {
type filter hook input priority 0; policy drop;
tcp dport 80 accept
}
}
packets:
- protocol: tcp
src_ip: 10.0.0.1
dst_ip: 10.0.0.2
dst_port: 80
expected_verdict: ACCEPT
- protocol: tcp
src_ip: 10.0.0.1
dst_ip: 10.0.0.2
dst_port: 22
expected_verdict: DROP
expected_verdict 是按数据包设置的。未知键会被拒绝,而不是采用默认值,因此拼写错误会导致测试套件失败,而不会悄悄变成你从未写过的预期。
以 root 权限运行测试套件:
sudo nse-runner --file firewall_test.yaml
退出码:0 表示所有数据包均匹配;1 表示某个判定错误或引擎无法观测到该判定。Oracle 错误与防火墙失败分开报告,因为它们意味着测量本身出了问题,而不是规则集有问题。
podman build -t nse .
podman run --rm --cap-add=NET_ADMIN --cap-add=NET_RAW \
-v "$PWD/firewall_test.yaml:/suite.yaml:ro" nse --file /suite.yaml
用于固定你的规则所针对测试的 nftables 版本。
NSE 通过结构化的多阶段执行流水线来编排 Linux 内核网络子系统和跟踪接口:
graph TD
subgraph Step1["1. Test Specification"]
Req["<b>TestRequest</b><br/>ruleset + packets + topology"]
end
subgraph Step2["2. Ephemeral Netns Sandbox"]
direction TB
Netns["<b>Netns Setup</b><br/>nse_<id> & veth links"]
RuleEng["<b>Rule Engine</b><br/>validate & load nftables"]
Inject["<b>Scapy Injector</b><br/>L2/L3 packet injection"]
NFT["<b>Kernel nftables</b><br/>meta nftrace set 1"]
Netns --> RuleEng
RuleEng --> Inject
Inject --> NFT
end
subgraph Step3["3. Trace Evaluation & Oracle"]
direction TB
Harvester["<b>Trace Harvester</b><br/>nft monitor trace stream"]
Oracle["<b>Deterministic Oracle</b><br/>TraceEvents & verdicts"]