Zenith（齐天）

L2→L7 全栈网络安全数据面框架：AF_XDP + eBPF + TLS 1.3 + HTTP/1-2-3 + Web + Proxy + WAF + Cache + Fingerprint + Forward

从内核旁路到应用层的完整 Rust 网络框架，既能构建系统级网络防火墙，也能构建 CDN 边缘节点和 API 网关。

项目介绍 · 快速上手 · 安全报告 · 赞助公示 · 参与贡献 · 商业授权

Zenith 是一个面向极端性能场景的L2→L7 全栈网络安全数据面框架，采用 feature-gated facade 设计， 用户可按需启用所需能力，避免拖入不必要的重依赖（如 libbpf-rs、rustls、ring）。 在 Linux 上启用 AF_XDP/eBPF/io_uring 零拷贝数据面，在 Windows/其他平台自动降级到 std::net 仍全功能可用。

📚 文档导航

📜 许可证

Zenith 采用多许可证模型发布，您可以为自己的用例任选其一：

• GPL-2.0 — 适用开源项目与社区贡献
• MIT — 适用追求最大灵活性、易于集成的场景
• Apache-2.0 — 适用需要明确专利授权与企业合规的场景

有关企业支持、闭源商用与许可证选型的详细信息，请参阅 COMMERCIAL.md。

⚙️ 核心能力

🛡️ 系统级网络防火墙能力（L2→L4）

Zenith 区别于普通 Web 框架的核心——具备构建系统级网络防火墙的全部基础组件：

🔐 安全能力

🔄 跨平台自动降级

高性能环境 (XDP Native + AF_XDP + 零拷贝 + BTF/CO-RE)
  → Performance (tier=3)  splice(2) + io_uring + AF_XDP + eBPF 全启用

中等环境 (XDP Generic + BPF，无 Native/零拷贝)
  → Balanced (tier=2)  XDP Generic + BPF，io_uring 可用

低能力环境 (无 XDP/AF_XDP/eBPF，如 Windows/最小容器)
  → Minimal (tier=1)  仅 std::net basic_socket，TcpRelay 回退 std::io::copy
  → WAF/代理/缓存/路由/转发 全功能可用

EnvironmentDetector 真实探测 → ProfileSelector 多目标评分自动选择 → degrade() 三级降级链。

🔄 运行时热更新（全链路 L2→L7）

作为依赖库，除固定协议规范标准外，所有运行参数均支持运行时热更新（无需重建服务器/引擎），实现最高自由度：

• L7 web — server.update_runtime(|r| ...) 无锁原子热更新：WAF 开关/按 host 黑白名单/规则集、指纹安全/限流/阻断、UDP/L4 转发会话、Supervisor 熔断、HTTP/1.1 请求上限/空闲超时、请求体上限、读/写缓冲、HTTP/2 帧长/并发流、HTTP/3 字段段、/metrics 令牌、监听地址、缓存容量
• L7 代理 — set_proxy_config/update_proxy_config：ProxyConfig 20+ 旋钮；转发超时对既有路由立即生效，池/健康阈值对新路由生效
• L4 转发 — set_forward_config：ForwardConfig（并发会话上限/单会话带宽）即时生效
• L2/L3 — eBPF config_map（MTU/协议白名单/fail-closed/期望策略）、XskConfig 收发缓冲/预填分块、每包解析预算 parse_packet_with_budget

性能：热路径标量一律 AtomicU64/AtomicBool 单指令原子加载（零锁零竞争）；host 名单仅启用时才触碰 RwLock；写（热更新）低于微秒级，不触碰读热路径，更新对所有 clone 副本立即生效。 固定内容：协议规范常量（头长、帧长、MTU 标准值、QUIC 版本等）与 Worker MAX_BATCH_SIZE（固定栈数组零堆分配优化）不可改。

📦 按需导入

Zenith 默认仅启用最小核心（api + core），其余能力按需开启。

最小依赖（仅类型定义）

[dependencies]
zenith = { path = "...", default-features = false, features = ["api"] }

use zenith::api::{CanonicalRequest, Method};

let mut req = CanonicalRequest::empty();
req.method = Method::Get;
req.set_path("/api/users");

仅 Web 框架（不拖入 AF_XDP / eBPF / 运行时数据面）

[dependencies]
zenith = { path = "...", default-features = false, features = ["web"] }

use zenith::web::{App, WebError};
use zenith::api::{CanonicalRequest, CanonicalResponse};

let mut app = App::new();
app.get("/health", |_req, _params| Ok(CanonicalResponse::new(204)));

仅 HTTP 协议解析（无 Linux 数据面）

[dependencies]
zenith = { path = "...", default-features = false, features = ["http"] }

完整生产协议栈

[dependencies]
zenith = { path = "...", features = ["full-stack"] }

全部能力（含测试工具）

[dependencies]
zenith = { path = "...", features = ["full"] }

🧩 Feature 矩阵

📥 直接引用子 crate

除使用 facade 外，也可直接引用单个子 crate（适合只需求某一独立能力的场景）：

[dependencies]
zenith-web = { path = ".../zenith/crates/zenith-web" }

子 crate 的 default 特性均为空，仅包含必需依赖。

🎯 设计原则

• Fail-Closed：探测/构建/解析失败取安全默认值，永不 panic
• 热路径零堆分配：固定容量数组替代 String/Vec
• 单线程本地存储：无锁访问、对象池复用
• 编译期路由注册：运行期零开销分发
• unsafe 隔离：所有 unsafe 封装在 zenith-linux/zenith-ebpf 内部，上层零 unsafe
• Copy 语义：核心类型支持 Copy，避免 Clone 开销
• 代际安全：证书/配置双 Bank 原子切换
• 恒定时间比较：DCID/Token/密码/模式匹配防时序侧信道，core::hint::black_box 增强
• L2→L7 全栈：从网卡驱动层包过滤到应用层 WAF，单一代码库覆盖完整网络安全数据面
• 跨平台兼容：Linux 极致性能，Windows/其他平台自动降级仍全功能可用

✅ 协议合规验证（真实进程级）

🧪 测试

# 全量测试（含所有特性）
cargo test --workspace --all-features

# 仅默认特性
cargo test -p zenith

# 单 crate 测试
cargo test -p zenith-web

当前测试基线：3235 项通过 / 0 失败（53 套件，cargo test --workspace --all-features）。安全审计修复后基线：aws-lc-rs 已从依赖树彻底移除（rustls + ring 为唯一密码学后端）。

安全审计修复项

v1 审计修复（9 项代码 + 4 项文档）：

• detection.rs：VmLk 字段名修正（原 MaxLockedMemory 不存在于 /proc/self/status）
• runtime.rs：start() 控制线程失败时回滚状态到 Created
• static.rs：read_range 统一使用 open_nofollow（TOCTOU 符号链接窗口）
• cert_manager.rs：代际 ID 溢出改用 saturating_add
• quic.rs：cipher_suite() 从 negotiated_cipher_suite() 读取实际协商结果
• audit.rs：clear() 增加置 None 清理残留字节
• supervisor.rs：DomainSupervisor::shutdown 清理 queues ChildSet
• sni.rs：Sniprovider → SniProvider；SNI 统一 to_ascii_lowercase()
• graph.rs：InsufficientResources 字段语义修正 + worker_id_counter 溢出保护

v2 综合审计（31 个任务，约 100 个子任务）：2 CRITICAL + 4 HIGH + 9 P1 MEDIUM + 9 P2 + 8 LOW

• AuthMiddleware 凭据校验（默认 require_non_empty，可选恒定时间比较）
• QUIC 流表索引（H3 stream ID 取模 u64 空间）
• H3 响应大小限制（drive_h3 强制 max_response_bytes）
• TCP 连接表 off-by-one（free_stack O(1) 槽位）
• ForwardLease Drop（panic 时防连接池泄漏）
• WAF NULL 字节过滤 + SQLi/XSS/路径穿越模式扩展
• 私钥零化（Zeroizing<PrivateKeyDer>）
• CORS 安全默认（allow_origin 默认为空）
• X-Forwarded-For、ct_compare black_box、QUIC STOP_SENDING 独立解析、CRYPTO 缓冲 65536、ChunkedDecoder trailer 8192、TimerWheel 钳位、连接池精确索引

v3 22 维度审计（4 High + 21 Medium + 18 Low）：

• BPF bpf_redirect_map flags 改为 XDP_PASS
• detect_locked_memory_kb 用 getrlimit(RLIMIT_MEMLOCK) 读取上限
• ct_compare 衍生函数添加 black_box
• 指纹评分模型引入白名单/黑名单
• 指纹向量槽位冲突修复（新增 TlsAlertSig/QuicExtOrder/TimingRttMs 独立变体）
• DecisionAction→EnforcementAction 映射、ForwardEngine 无白名单 fail-closed
• LRU/FIFO 用 BTreeMap O(log n)、Histogram Prometheus 格式、PermissionSet u16、QoS 继承、TCP ACK 校验、审计脱敏

v4 22 维度系统级再审计（6 P0 + 12 P1 + 20 P2）：

• ct_compare 全函数 black_box、ChunkedSig 槽位拆分、Blacklist FxHashSet O(1)
• TCP SynReceived 簿记修正、ExpectationConfig 布局对齐、/metrics Bearer 认证
• QPACK 总字节上限接线、ForwardEngine 三态、Histogram 双花括号、timer_wheel 死重移除、UMEM incref TOCTOU、smuggling 去重、escape_json 去重

v5-v7 深度再审计（多轮闭环）：

• QUIC 保留位 Fixed Bit(0x40) 校验（RFC 9000 §17.2）
• BPF queue_map 跨 crate 缺失（Rust BpfMaps 移除残留字段）
• BPF 分片策略首分片逃逸（frag_off & 0x3FFF，重编 .o）
• WAF NULL 字节 SQLi fail-open 修复（就地压缩删除，保留 NULL 后载荷）
• runtime assign_domain 防超卖 + extreme_planner 容错
• 指纹评分 RTT 维度覆盖、XdpPolicyWriter 恒 Err 移除、死代码清理（workspace 0 警告）

v8 全链路修复与加固（zenith-fix-hardening，246 项审计发现中可落地项）：

• 恒定时间比较（CORE-001/002/026）：ct_compare 5 函数移除提前返回，长度差经累加器聚合，消除令牌/签名时序侧信道
• FramePool/Ledger 一致性（CORE-004/006/007/008/009/011/012/013/023/024/031）：release 错误路径回滚、守恒等式异常路径不破坏、双重计数修正
• L4 转发资源耗尽（APP-010/030）：中继 SO_RCVTIMEO + splice 超时双向 shutdown 回收半开连接
• HTTP/1-2-3 解析（HTTP-002/004/015/016/020/023/027/035）：HPACK 动态表溢出、CONTINUATION 非法通过、QPACK Huffman 位复核（HTTP-025 为审计误报）；额外修复 hpack decode_integer 绝对/相对步长 bug（http2 10 fail 清零）
• 0-RTT 重放/降级（TLS-003/004/011）：默认 max_early_data_size=0 + 60s 重放窗口 + TLS1.3 强制校验
• eBPF/XDP 过滤链（NET-016/011/010/013/014）：默认 Bank 走 xdp_main、IPv6 扩展头 PASS、分片策略 1 fail-closed、白名单单一权威来源（WSL2 无法真实挂载，静态修复 + make -C bpf clang 编译验证）
• WAF 误报收敛（APP-014/015/017）：裸单字符操作符/内网 IP 全段扫描收敛，威胁仍 403、良性 200
• 系统/运行时/代理（SYS-005/006/008/011/014/016/021/024/026 + APP-023/026/028 + NET-018/019/028）：背压账本、自动降级阈值、CPU 亲和映射、Cache-Control 严格合并、审计环形缓冲 fail-closed、Header 合并 DoS、H2 响应头上限、HalfOpen 限并发、带宽真实节流、CIDR 匹配、跨族通配、SYN-ACK ISN 校验
• TCP 状态机加固（NET-020/021）：handle_new_syn 非监听 fail-closed、off-path FIN/RST 接入 is_seq_in_rcv_window 窗口校验
• 错误分层（ENG-006/007/012/013/015）：ServerError::Http3 统一 H3 双路径、WebError 结构化、前缀整数/varint 收敛 core、方法单一解析器
• H3 coalesced 1-RTT 竞态：quic_server 三处守卫（coalesced long/short + 独立 short 路径）握手未完成时推迟到 pending_1rtt，消除 DecryptError
• 验证：h2spec 146/146、h3spec 49/49、四协议 curl.exe 全 200、IPv6 200、wrk 55,847/79,006 req/s（远超 25k 门槛）、hping3 SYN 514k/UDP 902k 洪水后存活、威胁 403/良性 200、JA3/JA4 阻断（含 H3 QUIC）、L2/L3/L4 23/23+10/10、热更新 18/18

🛠️ 构建要求

• Rust 1.97.1+（Stable，禁止 Nightly/Beta），edition 2024
• Linux 内核 5.4+（启用 linux / ebpf / runtime 特性时）
• libbpf 1.0+（启用 linux / ebpf 特性时）
• Windows/macOS：无需特殊依赖，自动降级到 std::net

📜 License

Zenith 采用多许可证模型发布，您可以为自己的用例任选其一：

• GPL-2.0 — 见 LICENSE-GPL2
• MIT — 见 LICENSE-MIT
• Apache-2.0 — 见 LICENSE-APACHE

完整的选型指南、企业支持与闭源商用方案请参阅 COMMERCIAL.md。