NoFear0411/spliff
GitHub: NoFear0411/spliff
一款利用 eBPF（XDP 与 uprobes）无需 MITM 代理即可实时嗅探并解析 SSL/TLS 加密流量的开源 EDR 探针工具。
Stars: 12 | Forks: 0
# spliff
**基于 eBPF 的 SSL/TLS 流量嗅探器**
[](CHANGELOG.md)
[](https://github.com/NoFear0411/spliff/actions/workflows/release.yml)
[](LICENSE)
[](CMakeLists.txt)
无需 MITM 代理即可实时捕获和检查解密的 HTTPS 流量。spliff 使用 eBPF uprobes 挂钩 SSL/TLS 库函数，在数据解密后但到达应用程序之前对其进行拦截。
**该项目完全由 Claude Opus 编写，目标是在 AI 的帮助下构建一个完整的 EDR/XDR 开源代理/平台**
## 功能
### SSL/TLS 库支持
- **OpenSSL**：`SSL_read`、`SSL_write`、`SSL_read_ex`、`SSL_write_ex`、`SSL_connect`
- **BoringSSL** ⚠️：对 Chrome/Chromium/Brave/ 的实验性支持（参见[已知限制](#known-limitations)）
- **GnuTLS**：`gnutls_record_recv`、`gnutls_record_send`、`gnutls_handshake`
- **NSS/NSPR**：`PR_Read`、`PR_Write`、`PR_Recv`、`PR_Send`、`SSL_ForceHandshake`
- **WolfSSL**：`wolfSSL_read`、`wolfSSL_write`
### HTTP 协议支持
| Protocol | Parser | Features |
|----------|---------|----------|
| HTTP/1.1 | llhttp | 完整的 header 解析、分块传输编码、body 聚合、请求-响应关联 |
| HTTP/2 | nghttp2 | 帧解析、HPACK 解压、流跟踪、流中恢复、多路复用的请求/响应关联 |
### 流关联与线程安全
- **双索引流查找**：通过 socket cookie 索引 + shadow 索引（pid, ssl_ctx）实现 O(1) 关联
- **IPv6 完全关联**：使用独立的 BPF map 实现零冲突的 40 字节流 key
- **动态流池**：通过 jemalloc 按需分配并进行缓存行对齐
- **Generation Counters**：跨工作线程的安全指针验证
- **RCU 安全内存**：使用 liburcu `call_rcu()` 实现安全的哈希表延迟释放
- **引用计数**：基于原子 ref_count 的生命周期管理可防止在清理期间发生 use-after-free (v0.10.0)
### XDP 数据包级跟踪
- **高性能流跟踪**：网络接口级别的 XDP 程序
- **自动附加**：发现并附加到所有合适的接口（原生支持并带有 SKB 回退机制）
- **协议检测**：在数据包级别进行 TLS、HTTP/2、HTTP/1.x 分类
- **sock_ops Cookie 缓存**：数据包与 SSL 会话之间的“金线 (Golden Thread)”关联
- **双重预热策略**：使用 BPF map + Netlink SOCK_DIAG 处理预先存在的连接
### 多线程架构
- **SPMC 环传输**：带有镜像缓冲区零拷贝的 Vyukov 式单生产者多消费者环 (v0.10.0)
- **连接亲和性**：`hash(pid, ssl_ctx)` 路由至一致的工作线程并具有 MPSC 溢出处理 (v0.10.0)
- **背压控制**：四级迟滞状态机（NORMAL→WARN→CRITICAL→SHED）(v0.10.0)
- **每流 HTTP/2 会话**：每个流具有 64 个流池，并带有 O(1) 空闲列表分配
- **异步 MPSC 日志记录器**：带有 eventfd 通知的无锁日志 pipeline
- **延迟显示队列**：在显示前等待 XDP 关联完成（100ms 超时）
- **流式解压**：基于流的 gzip/zstd/brotli 解压，带有炸弹保护（拒绝 >1000:1 的压缩率）(v0.10.0)
### BPF 级别过滤
- **Socket Family 检测**：在内核级别过滤 AF_UNIX (IPC)
- **动态 cgroup2 检测**：解析 `/proc/mounts` 以查找任何 cgroup2 挂载
- **SSL 会话跟踪**：将 SSL* 映射到文件描述符以进行 socket 查找
- **NSS SSL 验证**：过滤非 SSL 的 NSPR 文件描述符
### 动态进程监控
- **EDR 式进程扫描**：通过 `/proc/PID/maps` 发现 SSL 库
- **运行时浏览器检测**：检测 Chrome/Chromium/Brave（实验性）
- **进程生命周期事件**：用于 exec、fork 和 exit 的 BPF tracepoints
- **内嵌 BPF Skeleton**：单一二进制部署，内嵌 bytecode
### 会话统计
- **统一关闭报告**：在退出时收集所有子系统指标
- **生产级可见性**：每个构建版本中都包含完整的 pipeline 指标
- **XDP 分类**：数据包、流、关联成功率
### 高级功能
- **ALPN 检测**：挂钩 ALPN 协商，以进行明确的 HTTP/1.1 与 HTTP/2 检测
- **ALPN 显示**：显示协商的协议（例如，`ALPN:h2`、`ALPN:http/1.1`）
- **请求-响应关联**：响应显示关联的请求 URL（同时支持 HTTP/1.1 和 HTTP/2）
- **Body 解压**：gzip、deflate、zstd、brotli（自动）
- **文件签名检测**：通过 magic bytes 检测 50 多种格式（图像、视频、音频、归档文件、文档）
- **TLS 握手跟踪**：可选地显示握手事件及其延迟
- **动态库发现**：通过 `/proc/PID/maps` 查找 SSL 库（支持 Flatpak/Snap）
- **进程树过滤**：按 PID、父 PID 或进程名进行过滤
## 环境要求
- Linux 内核 5.x+ 并带有 BTF 支持
- Root 权限（用于 eBPF）
- clang（用于 BPF 编译）
### 依赖项
| Library | Purpose | Package (Fedora) | Package (Debian/Ubuntu) |
|---------|---------|------------------|-------------------------|
| libbpf | eBPF CO-RE 加载器 | libbpf-devel | libbpf-dev |
| libelf | ELF 解析 | elfutils-libelf-devel | libelf-dev |
| zlib-ng | SIMD gzip 解压 | zlib-ng-devel | (build from source) |
| llhttp | HTTP/1.1 解析 | llhttp-devel | libllhttp-dev |
| nghttp2 | HTTP/2 解析 | libnghttp2-devel | libnghttp2-dev |
| ck | 无锁数据结构 | ck-devel | libck-dev |
| libxdp | XDP 程序加载 | libxdp-devel | libxdp-dev |
| liburcu | Read-Copy-Update | userspace-rcu-devel | liburcu-dev |
| jemalloc | 内存分配器 | jemalloc-devel | libjemalloc-dev |
| vectorscan | O(n) 协议检测 | vectorscan-devel | (build from source) |
| pcre2 | 模式匹配回退 | pcre2-devel | libpcre2-dev |
| zstd | zstd 解压 | libzstd-devel | libzstd-dev |
| brotli | brotli 解压 | brotli-devel | libbrotli-dev |
### 快速安装 (Fedora)
```
sudo dnf install libbpf-devel elfutils-libelf-devel zlib-ng-devel \
llhttp-devel libnghttp2-devel ck-devel libxdp-devel userspace-rcu-devel \
jemalloc-devel vectorscan-devel pcre2-devel libzstd-devel brotli-devel clang
```
### 快速安装 (Debian/Ubuntu)
```
sudo apt install libbpf-dev libelf-dev zlib1g-dev \
libllhttp-dev libnghttp2-dev libck-dev libxdp-dev liburcu-dev \
libjemalloc-dev libpcre2-dev libzstd-dev libbrotli-dev clang
# vectorscan 和 zlib-ng：请首先检查您的 distro 仓库，否则请从源码构建：
# - https://github.com/VectorCamp/vectorscan
# - https://github.com/zlib-ng/zlib-ng
```
## 安装说明
### 从源码构建
```
# 克隆仓库
git clone https://github.com/NoFear0411/spliff.git
cd spliff
# 构建（带 sanitizers 的 debug 模式）
make
# 或者构建优化后的 release 版本
make release
# 进行系统级安装
sudo make install
```
### 构建选项
| Target | Description |
|--------|-------------|
| `make` / `make debug` | 带有 sanitizers (ASan, UBSan) 的调试构建 |
| `make release` | 优化并精简的二进制文件 |
| `make relsan` | 带有 sanitizers 的优化构建（用于测试） |
| `make tests` | 构建并运行全部 17 个测试套件 |
| `make test-ring` | 仅运行环传输测试（5 个套件） |
| `make test-protocol` | 仅运行协议解析器测试（4 个套件） |
| `make test-flow` | 仅运行流上下文测试（2 个套件） |
| `make test-content` | 仅运行解压测试（2 个套件） |
| `make test-memory` | 仅运行内存基础设施测试（1 个套件） |
| `make test-util` | 仅运行实用工具测试（3 个套件） |
| `make docs` | 生成 Doxygen API 文档 |
| `make clean` | 删除构建产物 |
| `make install` | 安装到 /usr/local/bin |
| `make package-deb` | 创建 Debian 软件包 |
| `make package-rpm` | 创建 RPM 软件包 |
### API 文档
使用 Doxygen 生成全面的 API 文档：
```
# 生成 HTML 文档
make docs
# 查看文档
xdg-open build/docs/html/index.html
```
文档包含：
- 带有 ASCII 图表的架构概述
- 线程模型和数据流文档
- 无锁数据结构说明
- 各模块 API 参考（包含参数和返回值）
### 测试
构建并运行完整的测试套件（17 个套件）：
```
# 构建并运行所有测试
make tests
# 或者运行单独的 module 组
make test-ring # Ring transport tests (5 suites)
make test-protocol # Protocol parser tests (4 suites)
make test-flow # Flow context tests (2 suites)
make test-content # Decompression tests (2 suites)
make test-memory # Memory tests (1 suite)
make test-util # Utility tests (3 suites)
```
| Test Suite | Module | Coverage |
|------------|--------|----------|
| test_http1 | protocol | 使用 llhttp 进行 HTTP/1.x 请求/响应解析 |
| test_http2 | protocol | 使用 nghttp2 进行 HTTP/2 preface、frames、验证 |
| test_detector | protocol | Vectorscan 协议检测模式 |
| test_websocket | protocol | RFC 6455 帧解析、masking、分片 |
| test_flow_context | flow | 双索引关联、流池、流管理 |
| test_flow_refcount | flow | 引用计数生命周期 (v0.10.0) |
| test_spmc_ring | ring | SPMC 环形缓冲区操作 (v0.10.0) |
| test_concurrent | ring | 多线程环形压力测试 (v0.10.0) |
| test_affinity | ring | 亲和性路由和 MPSC 溢出 (v0.10.0) |
| test_backpressure | ring | 四级迟滞状态机 (v0.10.0) |
| test_worker_dequeue | ring | 三阶段消耗 + 自适应轮询 (v0.10.0) |
| test_decompressor | content | 每个事务的 gzip、deflate、zstd、brotli 解压 |
| test_stream_decompressor | content | 流式解压 + 炸弹保护 (v0.10.0) |
| test_mirrored_buffer | memory | 镜像虚拟内存缓冲区 (v0.10.0) |
| test_safe_str | util | 内存安全的字符串操作 |
| test_display | util | 颜色输出、延迟格式化、时间戳 |
| test_xdp | util | XDP 事件结构验证 |
### CMake 选项
```
cmake -B build -DCMAKE_BUILD_TYPE=Release \
-DENABLE_SANITIZERS=OFF \
-DENABLE_ZSTD=ON \
-DENABLE_BROTLI=ON \
-DUSE_VECTORSCAN=ON \
-DUSE_ZLIB_NG=ON
cmake --build build
```
| Option | Default | Description |
|--------|---------|-------------|
| `USE_VECTORSCAN` | ON | 使用 vectorscan 进行 O(n) 协议检测 |
| `USE_ZLIB_NG` | ON | 使用 zlib-ng 进行 SIMD 加速压缩 |
| `ENABLE_LTO` | ON | 链接时优化（速度提升 5-10%，二进制文件更小） |
| `ENABLE_ZSTD` | ON | 启用 zstd 解压 |
| `ENABLE_BROTLI` | ON | 启用 brotli 解压 |
| `ENABLE_SANITIZERS` | OFF | 启用 AddressSanitizer/UBSan（用于调试构建） |
## 使用说明
```
# 基本用法（捕获所有 SSL 流量）
sudo ./spliff
# 按进程过滤
sudo ./spliff -p 1234 # By PID
sudo ./spliff -p 1234,5678 # Multiple PIDs
sudo ./spliff --comm curl # By process name or path
sudo ./spliff --ppid 1234 # By parent PID (captures all children)
# 按 SSL 库过滤
sudo ./spliff --openssl # OpenSSL only
sudo ./spliff --gnutls # GnuTLS only
sudo ./spliff --nss # NSS only
# 输出选项
sudo ./spliff -b # Show request/response bodies
sudo ./spliff -x # Hexdump body with file signatures
sudo ./spliff -c # Compact mode (hide headers)
sudo ./spliff -l # Show latency (SSL operation time)
sudo ./spliff -H # Show TLS handshake events
sudo ./spliff -C # Disable colored output
# Threading 选项
sudo ./spliff -t 4 # Use 4 worker threads
sudo ./spliff -t 0 # Auto (default): max(1, CPUs-3), capped at 16
# 特定于 Browser 的（IPC 过滤是自动的）
sudo ./spliff --comm firefox # Firefox traffic
sudo ./spliff --nss --ppid 1234 # NSS traffic from Firefox children
# 调试
sudo ./spliff -d # Debug mode (verbose output)
sudo ./spliff --show-libs # Show all discovered SSL libraries
```
## 输出示例
### HTTP/2 请求/响应（带有 XDP 关联）
```
04:35:19.750 → GET https://httpbin.org/bytes/16384 ALPN:h2 curl (855771) [stream 1] #648f
|- 192.168.50.245:42696 → 44.197.91.61:443 [XDP:TLS][App:H2] ✓✓ (wlp0s20f3)
04:35:20.363 ← 200 https://httpbin.org/bytes/16384 ALPN:h2 application/octet-stream (16384 bytes) curl (855771) [614.81ms] [stream 1] #648f
|- 44.197.91.61:443 → 192.168.50.245:42696 [XDP:TLS][App:H2] ✓✓ (wlp0s20f3)
```
### HTTP/1.1 请求/响应（带有 XDP 关联）
```
04:35:45.555 → GET https://httpbin.org/get ALPN:http/1.1 curl (855994) [141.7us] #230f
|- 192.168.50.245:52274 → 52.204.75.48:443 [XDP:TLS][App:H1] ✓✓ (wlp0s20f3)
04:35:45.860 ← 200 https://httpbin.org/get ALPN:http/1.1 application/json (256 bytes) curl (855994) [170.9us] #230f
|- 52.204.75.48:443 → 192.168.50.245:52274 [XDP:TLS][App:H1] ✓✓ (wlp0s20f3)
```
### TLS 握手（带有 -H 标志）
```
15:12:05.100 🔒 TLS handshake 192.0.2.10:52418 → 203.0.113.50:443 [12.45ms] curl (403422)
```
### XDP 附加状态（启动时）
```
✓ XDP: enp0s20f0u2u4u2 [skb], wlp0s20f3 [skb], enp0s31f6 [skb]
```
## 架构
spliff 使用 eBPF uprobes 拦截已解密的 SSL/TLS 数据，使用 XDP 进行数据包级流跟踪，
并使用 sock_ops 进行 socket cookie 关联（“金线 / Golden Thread”）。多线程调度器
通过无锁的 SPSC 队列将事件路由到工作线程，并在动态池中通过双索引查找管理每个流的状态。
有关详细的图表和数据流，请参见[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 路线图
| | Theme | Key Deliverables | Status |
|---------|-------|------------------|--------|
| v0.1-0.8 | 核心 | 拦截、XDP 跟踪、多线程 | ✅ 完成 |
| v0.9.11 | 稳定性 | 无锁架构、线程安全、IPv6 | ✅ 完成 |
| **v0.10.0** | 基础 | Omni-Ring 内存、SPMC 环、引用计数的流、ZSTD 流式传输 | ✅ **当前** |
| v0.11.0 | 协议 | 明文 HTTP、WebSocket、gRPC、HTTP/3 + QUIC | 已规划 |
| v0.12.0 | 运维 | 增强调度器、全面指标 | 已规划 |
| v0.13.0+ | 强化 | 安全缓解措施、性能调优 | 已规划 |
| v1.0.0 | 发布 | 生产就绪、稳定的 API、所有协议 | 目标 |
| v2.0+ | EDR | 代理模式、事件流、威胁情报 | 未来 |
### 架构演进 (Omni-Ring)
v0.10+ 系列实现了 Omni-Ring 架构，以达到生产级性能：
- **零拷贝缓冲区**：镜像虚拟内存消除了回环绕过的分支
- **SPMC 工作线程**：带有批量出队的单生产者、多消费者环
- **引用计数**：无需基于 generation 的 hack 即可实现干净的流生命周期
- **多协议**：统一 HTTP/1、HTTP/2、HTTP/3、WebSocket、gRPC 的检测/路由
详细的实施计划请参见[docs/REFACTOR-PLAN.md](docs/REFACTOR-PLAN.md)。
### 目标
- **近期**：Omni-Ring 基础、明文 HTTP 捕获、WebSocket 集成
- **中期**：HTTP/3 + QUIC、全面的指标、安全强化
- **长期**：代理模式、NATS/Kafka 流式传输、行为分析、威胁情报
详细版本历史请参见[CHANGELOG.md](CHANGELOG.md)。
## 已知限制
有关已知限制、未解决的 bug 和变通方法，请参见[ISSUES.md](ISSUES.md)。
## 故障排除
有关常见问题和解决方案，请参见[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。
## 许可证
AGPL-3.0-only - 详情请参见[LICENSE](LICENSE)。
BPF 代码 (`src/bpf/spliff.bpf.c`) 采用 GPL-2.0-only 许可证（Linux 内核要求）。
## 致谢
### 核心库
- [libbpf](https://github.com/libbpf/libbpf) - 用于可移植 BPF 程序的 eBPF CO-RE 库
- [libelf](https://sourceware.org/elfutils/) - 用于库发现的 ELF 二进制解析
- [libxdp](https://github.com/xdp-project/xdp-tools) - XDP 程序加载和管理
### 协议解析
- [llhttp](https://github.com/nodejs/llhttp) - 来自 Node.js 的 HTTP/1.1 解析器
- [nghttp2](https://github.com/nghttp2/nghttp2) - 带有 HPACK 压缩的 HTTP/2 库
- [vectorscan](https://github.com/VectorCamp/vectorscan) - O(n) 模式匹配（Hyperscan 的分支）
- [PCRE2](https://github.com/PCRE2Project/pcre2) - Perl 兼容正则表达式
### 并发与内存
- [Concurrency Kit](https://github.com/concurrencykit/ck) - 无锁数据结构（SPSC 环）
- [liburcu](https://liburcu.org/) - 用户空间 Read-Copy-Update
- [jemalloc](https://github.com/jemalloc/jemalloc) - 内存分配器
### 压缩
- [zlib-ng](https://github.com/zlib-ng/zlib-ng) - SIMD 优化的 gzip/deflate 解压
- [zstd](https://github.com/facebook/zstd) - 由 Facebook 开发的 Zstandard 压缩算法
- [brotli](https://github.com/google/brotli) - 由 Google 开发的 Brotli 压缩算法
### 文档
- [Doxygen](https://www.doxygen.nl/) - API 文档生成工具
### 技术资源
- [Linux kernel BPF documentation](https://docs.kernel.org/bpf/) - 官方 BPF 文档
- [XDP Tutorial](https://github.com/xdp-project/xdp-tutorial) - 实践 XDP 编程
- [RFC 7540](https://datatracker.ietf.org/doc/html/rfc7540) - HTTP/2 规范
- [RFC 7541](https://datatracker.ietf.org/doc/html/rfc7541) - HPACK header 压缩
### 开发
- Anthropic 的 [Claude](https://www.anthropic.com/claude) - 编写此代码库的 AI 助手
- [Claude Code](https://claude.ai/code) - 用于 AI 辅助开发的 CLI 工具
会话统计输出示例
``` ============================================ Session Statistics ============================================ Application Layer (SSL/TLS) ---------------------------------------------- Events: 131 captured -> 216 processed Output: 0 messages (0 B) Async Logger ---------------------------------------------- Messages: 36 (8.9 KB) Batches: 34 (avg 1.1 msgs/batch) Workers (16) ---------------------------------------------- Worker 1: 1 events Worker 2: 8 events Worker 4: 6 events Worker 5: 1 events Worker 6: 152 events Worker 7: 10 events Worker 8: 1 events Worker 9: 24 events Worker 11: 1 events Worker 14: 4 events Worker 15: 8 events CPU: Good (NAPI-style, 12162 sleep cycles) Flow Pool ---------------------------------------------- Active: 9 flows, peak 9 Throughput: 15 allocs, 6 frees Cookie index: 3 entries, 193 hits (95.5%), 9 misses Shadow index: 2 entries, 14 hits, 0 promotions Promotion: 0.0% of flows got socket_cookie Network Layer (XDP) ---------------------------------------------- Packets: 205 processed (177 TCP) Connections: 9 tracked, 9 classified Correlation: 100.0% socket cookie success Classified: 9 flows Ambiguous: 76 (deeper inspection needed) Terminated: 6 (FIN/RST) Cache hits: 0 (fast-path gatekeeper) Cookie miss: 0 (correlation gaps) Sockops (cookie caching) ---------------------------------------------- Events: 5 (active: 5, passive: 0) Cleanup: 0 SSL Probes ---------------------------------------------- SSL_read/SSL_write intercepted: 41 ============================================ ```标签：Bash脚本, Docker镜像, EDR, SSL/TLS解密, XDP, 客户端加密, 流量监控, 网络安全, 脆弱性评估, 防御绕过, 隐私保护