AlexeyVasilev/PcapConstrictorBPF

# PcapConstrictorBPF PcapConstrictorBPF 是一个实验性的 Linux TC eBPF 数据包记录器， 它能在实时捕获过程中将流量录制为经典的 PCAP 文件，并应用一小部分 支持 TLS/QUIC 感知的压缩策略。 它与 [PcapConstrictor](https://github.com/AlexeyVasilev/PcapConstrictor) 相关，但 并非旨在取代它。主要的 PcapConstrictor 项目仍然是更强大的 离线 PCAP/PCAPNG 压缩工具。PcapConstrictorBPF 的范围更窄， 更具教育意义：它适用于学习 TC 挂钩、对验证器友好的 BPF 解析、BPF 映射、环形缓冲区以及自适应捕获策略。 如需实用的 Linux 实时捕获，请使用 [PcapConstrictorAFPacket](https://github.com/AlexeyVasilev/PcapConstrictorAFPacket)。 PcapConstrictorBPF 故意受到 eBPF 验证器限制，应 被理解为一个研究项目，而非主要的推荐 实时记录器。 ## 状态 实验性 / 研究导向的项目。该记录器在 Linux 上功能正常， 并演示了基于 TC eBPF 的自适应捕获、BPF 映射、对验证器友好的 数据包解析以及运行时策略配置。它故意实现了 比 PcapConstrictor 和 PcapConstrictorAFPacket 更窄的策略。 ## 项目家族 | 项目 | 角色 | 适用场景 | |---|---|---| | [PcapConstrictor](https://github.com/AlexeyVasilev/PcapConstrictor) | 主要的离线 PCAP/PCAPNG 压缩工具 | 当您已有捕获文件，并需要最丰富的策略支持时，包括 TLS final_only/stream/bulk、QUIC、PCAPNG、重新膨胀/恢复、校验和策略、统计信息和决策日志。 | | [PcapConstrictorAFPacket](https://github.com/AlexeyVasilev/PcapConstrictorAFPacket) | Linux AF_PACKET 实时记录器 | 当您需要实用的 Linux 实时捕获，并采用用户空间的 PcapConstrictor 风格策略时。支持 TLS final_only 和 QUIC CID 感知的短头部压缩，但不支持 TLS stream/bulk。 | | [PcapConstrictorWinPacket](https://github.com/AlexeyVasilev/PcapConstrictorWinPacket) | Windows Npcap/libpcap 实时记录器 | 当您需要使用 Npcap 进行实用的 Windows 实时捕获，并拥有与 AFPacket 类似的策略范围时。支持 TLS final_only 和 QUIC 已知 DCID 压缩，但不支持 TLS stream/bulk。 | | [PcapConstrictorBPF](https://github.com/AlexeyVasilev/PcapConstrictorBPF) | 实验性 Linux TC eBPF 记录器 | 当您想要一个研究性的 eBPF 项目，演示 TC 挂钩、BPF 映射、对验证器友好的解析以及更小的实时捕获策略子集时。 | ## 当前功能 - Linux 上的 TC 入口和出口捕获。 - 经典的 PCAP 输出。 - 通过 `config.ini` 进行运行时策略配置。 - 捕获上限为编译时设置的 `MAX_CAPTURE_LEN=4096`。 - 正确的 PCAP 长度语义： - `incl_len = 捕获的字节数` - `orig_len = 原始 skb 长度` - 简单的 TLS AppData 压缩： - 仅限 TCP/443 - TLS 记录必须始于 TCP 载荷偏移处 - 支持完整或部分的单条 TLS 应用数据记录 - `cap_len = payload_off + encrypted_snaplen` - QUIC 支持： - UDP/443 长头部检测 - DCID/SCID 学习 - 使用规范的 IPv4 UDP 四元组进行流感知的 CID 状态管理 - 基于预期方向 DCID 的短头部匹配 - 匹配的短头部压缩 - `cap_len = payload_off + max(quic_short_header_keep_packet_bytes, 1 + matched_dcid_len)` - 聚合的关闭统计信息。 与 AF_PACKET 和离线项目相比，这里的 TLS 缩减量要小得多，QUIC 支持范围也更窄。这是预期的结果：BPF 路径更倾向于简单的、对验证器友好的解析，而不是深度延续处理。 ## 限制 / 非目标 - 仅限 Linux。 - 需要 root 或等效能力，如 `CAP_NET_ADMIN`。 - 使用 TC `clsact` 挂钩。 - 实验性的、对验证器友好的 eBPF 实现。 - 不是推荐的实用实时记录器。 - BPF 验证器限制故意限制了策略深度和协议处理。 - QUIC 流状态目前主要针对 IPv4。 - 无 QUIC 解密。 - 无 QUIC 帧解析。 - 无 QUIC `NEW_CONNECTION_ID` 跟踪。 - 无 QUIC 迁移支持。 - 无 TCP 流重组。 - BPF 中无多记录 TLS 压缩。 - TLS 支持故意限制在 TCP 载荷起始处的简单 AppData 记录。 - TLS 延续处理故意比 PcapConstrictor 和 PcapConstrictorAFPacket 窄得多。 - QUIC 处理故意比 PcapConstrictor 和 PcapConstrictorAFPacket 窄得多。 - 当前构建中，大包受 `MAX_CAPTURE_LEN=4096` 限制。 - 清理操作会移除 `clsact` qdisc，因此也会移除附加到该接口的 TC 过滤器。对于这个演示项目这是可以接受的，但在真实系统上应谨慎使用。 ## 架构 ``` TC ingress/egress hook -> BPF metadata parser -> TLS/QUIC policy decision -> ringbuf event -> user-space PCAP writer ``` 主要的 BPF 映射： - `capture_config`：运行时捕获策略 - `capture_stats`：聚合计数器 - `quic_cids`：学习到的 QUIC CID 诊断信息 - `quic_flows`：用于方向 CID 匹配的 QUIC 流状态 - 用于保持 BPF 栈对验证器友好的临时映射 如果你想研究如何端到端构建一个 TC eBPF 设计：挂载点、BPF 映射、环形缓冲区事件、紧凑的元数据解析，以及在验证器限制内做出的策略决策，那么这个仓库是一个很好的选择。 ## 构建 当前仓库通过提供的 `Makefile` 构建： ``` make ``` 构建流程使用： - `bpftool btf dump file /sys/kernel/btf/vmlinux format c > src/vmlinux.h` - `clang -g -O2 -target bpf -D__TARGET_ARCH_x86 ... -c src/tcpcap.bpf.c` - `bpftool gen skeleton src/tcpcap.bpf.o > src/tcpcap.skel.h` - `cc -g -O2 ... src/tcpcap.c -o tcpcap ...` 预期依赖： - 支持 BPF 目标的 `clang` - `libbpf` - `bpftool` - Linux 头文件和支持 BPF 的内核 - `tc` / `iproute2` - `libelf` 和 `zlib` ## 测试环境 在 VirtualBox Linux 虚拟机中的 Ubuntu 上开发和测试，使用支持 BPF 的内核、`clang`、`bpftool`、`libbpf` 和 `iproute2` / `tc`。其他内核或工具链可能需要微小调整。 ## 使用 默认捕获： ``` sudo ./tcpcap enp0s3 out.pcap ``` 带配置捕获： ``` sudo ./tcpcap enp0s3 out.pcap --config config.example.ini ``` 清理： ``` sudo ./tcpcap enp0s3 --cleanup ``` 检查 TC 状态： ``` sudo tc qdisc show dev enp0s3 sudo tc filter show dev enp0s3 ingress sudo tc filter show dev enp0s3 egress ``` ## 配置 运行时策略从 `config.ini` 加载到 `pcapc_capture_config` 中。 [`config.example.ini`](config.example.ini) 展示了支持的格式。 支持的键： ### `[捕获]` - `default_snaplen` - `max_capture_len` ### `[tls]` - `encrypted_snaplen` ### `[quic]` - `short_header_keep_packet_bytes` - `require_dcid_match` - `allow_short_header_without_known_dcid` 注意： - `require_dcid_match` 在当前 BPF 策略中固定为 `true`。 - `allow_short_header_without_known_dcid` 在当前固定为 `false`。 - 包含这些键是为了策略清晰性和未来兼容性。 - 捕获值不能超过当前构建限制 `MAX_CAPTURE_LEN=4096`。 - 配置界面匹配当前 BPF 支持的特性子集；它不暴露 TLS stream/bulk 模式或 PCAPNG 输出，因为这些超出了此记录器的范围。 ## 关闭统计信息 关闭时，记录器会打印紧凑的聚合计数器。常见计数器包括： - `events_total` - `events_submitted` - `reason_tcp` - `reason_udp` - `reason_tls_app_data` - `reason_quic_long` - `reason_quic_short_candidate` - `tcp_443` - `udp_443` - `quic_long` - `quic_cid_learned` - `quic_cid_update` - `quic_flow_learned` - `quic_flow_update` - `quic_short_flow_match` - `quic_short_constricted` 注意： - `reason_quic_short_candidate` 当前表示一个流感知匹配的 QUIC 短头部。 - `quic_short_constricted` 统计被实际缩短的已匹配短头部数据包。 ## 许可证 Apache License 2.0。详见 [LICENSE](LICENSE)。 版权所有 2026 Alexey Vasilev。

标签：BPF映射, Docker镜像, PCAP, QUIC, TC, TLS, 实时捕获, 实验性, 客户端加密, 教育工具, 数据包记录器, 环形缓冲区, 目录遍历, 研究项目, 网络安全, 网络工具, 自适应捕获, 防御工具, 隐私保护, 验证器友好