eogod/wireprism

# WirePrism **用于实时流量和 PCAP 的高吞吐量网络流检测。** [][ci-workflow]  [][license] WirePrism 可以在流量仍在到达时，将捕获的数据包转化为有界、可查询的流状态。它在一个 Rust 进程中结合了捕获、流跟踪、传输重组、协议解析、内容转换、模式匹配、本地 API 和密集的 Web UI。 该引擎专为那些正确性和可预测资源使用至关重要的工作负载而构建：大型 PCAP、长时间运行的实时捕获、协议研究、网络取证和 CTF 流量分析。 ## 核心亮点 - **实时和离线输入** 通过 libpcap 支持，带有 BPF 过滤器、源丢弃计数器、可配置的捕获缓冲区和批处理的 PCAP 重放。 - **有状态流处理** 具有规范流键、TCP 序列跟踪、有界乱序重组、QUIC 连接路由和流分片 worker。 - **协议感知流** 为 HTTP、DNS、TLS、QUIC、WebSocket 以及越来越多的文本和二进制服务提供结构化消息索引。 - **内容检查** 支持文本、正则表达式和二进制模式；逻辑匹配偏移量；高亮切片；以及文本、hex、raw 或 base64 复制格式。 - **按需转换** 支持 URL 编码、gzip、HTTP 分块 body、gzip HTTP body 和压缩的 WebSocket 消息。 - **设计上的界限** 通过显式的流、解析器、内容、匹配、队列和 API 保留限制，而不是无界的共享状态。 - **负载下的可观测性** 监控队列压力、路由字节数、回退原因、热流遥测、数据包/字节偏斜、解析器未命中和每个分片的诊断。 - **内置本地 UI 和 API** 具有实时增量、服务过滤器、收藏夹、隐藏流、匹配导航和视口大小的内容读取。 ## 快速开始 ### 前置条件 WirePrism 目前针对 macOS 和 Linux。您需要当前稳定的 Rust 工具链、libpcap 开发文件、Clang 和 CMake。 在 macOS 上： ``` xcode-select --install brew install cmake ``` 在 Ubuntu 或 Debian 上： ``` sudo apt-get update sudo apt-get install -y build-essential pkg-config libpcap-dev clang cmake libclang-dev ``` 构建优化的二进制文件： ``` git clone https://github.com/eogod/wireprism.git cd wireprism cargo build --release ``` 这将生成： - `target/release/wireprism` - 捕获、分析、API 和 UI 运行时。 - `target/release/wireprism-load` - 可重复的负载和回归测试工具。 ### 检查 PCAP ``` ./target/release/wireprism \ --pcap capture.pcap \ --output findings.jsonl \ --api-listen 127.0.0.1:33111 ``` 在进程运行时打开 [http://127.0.0.1:33111](http://127.0.0.1:33111)。PCAP 处理完成后，API 将保持可用状态直到按 `Ctrl-C`，因此仍然可以检查保留的流。 ### 捕获实时流量 首先列出接口： ``` ./target/release/wireprism --list-interfaces ``` 从接口捕获并打开实时 UI： ``` sudo ./target/release/wireprism \ --iface en0 \ --capture-filter 'tcp or udp' \ --api-listen 127.0.0.1:33111 \ --workers 0 ``` 实时捕获需要打开所选接口的权限。以普通用户身份构建，仅在需要提升捕获权限时才提升已完成二进制文件的权限。 `--workers 0` 表示运行时使用可用的并行度。主运行时接受整数 worker 数量；`adaptive` worker 计划由 `wireprism-load` 提供，用于基准测试和容量选择。 ## 检查工作流 ### 模式匹配 模式是可重复的，并且可以在一次运行中组合： ``` ./target/release/wireprism \ --pcap capture.pcap \ --pattern 'token=' \ --regex 'flag\{[^}]+\}' \ --binary-pattern 'de ad be ef' \ --api-listen 127.0.0.1:33111 ``` - `--pattern` 执行字节精确的子串匹配。 - `--regex` 跨越块边界匹配面向字节的正则表达式。 - `--binary-pattern` 接受带有可选空格、冒号、下划线、破折号或 `0x` 前缀的十六进制字节。 匹配保留流方向和逻辑偏移量，允许 API 和 UI 仅请求高亮所需的内容窗口。 ### TLS 和 QUIC 密钥 对于现代 TLS 和 QUIC 捕获，使用兼容 NSS/SSLKEYLOGFILE 的密钥日志： ``` ./target/release/wireprism \ --pcap capture.pcap \ --tls-keylog /path/to/sslkeys.log \ --api-listen 127.0.0.1:33111 ``` Static-RSA TLS 1.0-1.2 捕获可以使用一个或多个 PEM 私钥： ``` ./target/release/wireprism \ --pcap capture.pcap \ --tls-rsa-key /path/to/server-key.pem ``` Static RSA 密钥无法解密 ECDHE 会话。密钥日志和私钥包含敏感材料，不应将其提交到代码仓库中。 ### JSONL 输出 分析模式输出有界的元数据和解析器事件，而无需将所有保留的负载内容复制到输出流中： ``` ./target/release/wireprism --pcap capture.pcap --output findings.jsonl ``` 数据包转储模式输出数据包级别的转储事件： ``` ./target/release/wireprism \ --pcap capture.pcap \ --mode dump \ --output packets.jsonl ``` ## 协议覆盖 | 层级 | 当前覆盖范围 | | --- | --- | | 链路层和网络层 | Ethernet、Linux SLL、BSD loopback、raw IP、IPv4 和 IPv6 | | 传输层 | TCP、UDP、ICMP 解码、TCP 重组和 QUIC 状态 | | 结构化消息 | HTTP/1-3、基于 UDP/TCP 的 DNS、TLS、QUIC 和 WebSocket | | 文本服务 | SSH、FTP、SMTP、POP3、IMAP、Redis 和 Memcached | | 二进制服务 | MQTT、AMQP、Postgres、MySQL、MongoDB、LDAP、SMB2 和 RDP | | 数据报元数据 | DHCP、NTP、SNMP、SSDP、NetBIOS 名称服务和 ICMPv4 | 覆盖范围因协议而异。列在文本、二进制或数据报服务下的协议目前可能仅提供检测、帧处理和选定的消息元数据，而不是针对每个操作的完整语义解码器。 ## 架构 ``` flowchart LR A["PCAP file or live interface"] --> B["Batched ingest"] B --> C["Route-only dispatcher"] C --> D["Stateful flow placement"] subgraph S["Flow shard"] E["Decode once"] --> F["Flow and transport state"] F --> G["TCP / QUIC reassembly"] G --> H["Detection and parsers"] H --> I["Content, patterns, transforms"] end D --> S S --> J["Coordinator"] J --> K["JSONL sinks"] J --> L["Live API"] L --> M["Web UI"] ``` 热路径遵循几个规则： 1. 数据包在其 worker 分片内仅解码一次。 2. 规范流保留一个所有者，以便反向流量到达相同的状态。 3. 繁重的 TCP 流工作可以使用有界的卸载通道而无需移动流所有权；符合条件的 UDP elephant flow 可以跨 worker 进行条带化处理。 4. Worker 输入、输出和卸载队列应用显式背压。 5. 流内容、解析器状态、匹配索引和 UI 增量具有独立的内存上限和驱逐策略。 6. 协调器拥有面向查询的视图状态，使慢速的 UI 客户端远离 worker 本地的可变状态。 ## 运行时调优 默认值对于本地分析而言足够保守。大型或长时间运行的捕获应当谨慎设置内存和队列预算。 | 选项 | 默认值 | 用途 | | --- | ---: | --- | | `--workers` | `0` | 流分片 worker；`0` 使用可用的并行度 | | `--batch-size` | `4096` | 每次接收批处理读取和分发的数据包 | | `--worker-queue-depth` | `4096` | 每个 worker 的有界输入队列 | | `--event-queue-depth` | `4096` | worker 到协调器的有界事件队列 | | `--max-flows` | `1000000` | 最大保留流状态 | | `--max-stream-content-bytes` | `268435456` | 全局保留内容预算 | | `--max-stream-content-bytes-per-stream` | `8388608` | 每流内容上限 | | `--health-interval-ms` | `1000` | 遥测间隔；`0` 禁用 | 具有显式容量限制的示例： ``` ./target/release/wireprism \ --pcap capture.pcap \ --workers 8 \ --batch-size 8192 \ --worker-queue-depth 8192 \ --event-queue-depth 8192 \ --max-flows 2000000 \ --max-stream-content-bytes 536870912 ``` 队列深度不能替代吞吐量。使用健康状态端点和负载测试工具来区分持续的 worker 饱和与短期突发、回退路由或单个合理的主导流。 ## 实时 API 该 API 仅供本地使用，没有身份验证。除非放在经过身份验证的代理之后，否则请将其绑定到回环地址。 | 端点 | 用途 | | --- | --- | | `GET /api/health` | 管道、解析器、队列、丢弃和分片遥测 | | `GET /api/service-profiles` | 内置和自定义服务配置 | | `GET /api/streams` | 基于游标的流清单和过滤器 | | `GET /api/streams/{id}` | 流元数据和当前视图状态 | | `GET /api/streams/{id}/messages` | 解析的协议消息索引 | | `GET /api/streams/{id}/matches` | 保留的模式匹配范围 | | `GET /api/streams/{id}/content` | 有界的 text、hex 或 raw 内容切片 | | `GET /api/live/deltas` | 长轮询流和遥测更新 | | `PATCH /api/streams/{id}/state` | 收藏或手动隐藏流 | | `POST /api/view/hide-rules` | 添加内存中的隐藏规则 | 示例： ``` curl http://127.0.0.1:33111/api/health curl 'http://127.0.0.1:33111/api/streams?profile=http&limit=50' curl 'http://127.0.0.1:33111/api/live/deltas?cursor=0&limit=1024&wait_ms=1000' curl 'http://127.0.0.1:33111/api/streams/123/messages?protocol=http1&limit=128' curl 'http://127.0.0.1:33111/api/streams/123/content?direction=a_to_b&start=0&len=65536&mode=text&transform=auto' ``` 流 ID 也会作为 `stream_id_hex` 返回，以便浏览器客户端可以保留完整的 64 位值，而不会损失 JavaScript 的数字精度。 ## 服务配置 配置文件按协议、服务、端口、内容类型或模式 ID 对流进行分组。它们还可以定义默认视图、转换链和隐藏规则模板。 ``` { "include_builtins": true, "profiles": [ { "id": "admin_web", "name": "Admin web", "priority": 150, "protocol": "tcp", "ports": [8080, 18080], "services": ["http"], "default_mode": "text", "default_transform": "auto", "default_transforms": ["http_chunked", "http_gzip", "url_decode"], "hide_rules": [{ "kind": "port", "value": 18080 }] } ] } ``` 使用以下命令加载文件： ``` ./target/release/wireprism \ --pcap capture.pcap \ --service-profile-file profiles.json \ --api-listen 127.0.0.1:33111 ``` ## 性能测试工具 `wireprism-load` 跨 worker 数量运行可重现的合成或基于 PCAP 的测试套件，并报告 packets/sec、bytes/sec、事件吞吐量、分片偏斜、回退率、流分布和规划器决策。 ``` ./target/release/wireprism-load \ --fixture http-requests \ --flows 100000 \ --workers 1,4,adaptive,0 \ --runs 3 \ --warmups 1 \ --output perf-http.json ``` 可用的合成测试工具： - `http-requests` - `out-of-order-http` - `http-keep-alive` - `mixed-services` - `udp-elephant` - `tcp-elephant` 重放真实的捕获： ``` ./target/release/wireprism-load \ --pcap capture.pcap \ --workers 1,4,adaptive,0 \ --runs 3 \ --warmups 1 \ --output perf-pcap.json ``` 使用保存的 JSON 报告作为回归基准： ``` ./target/release/wireprism-load \ --fixture http-requests \ --flows 100000 \ --workers adaptive \ --runs 5 \ --warmups 2 \ --baseline baselines/http.json \ --max-regression-pct 10 \ --fail-on-regression \ --output perf-current.json ``` 除非设置了 `--include-warmups`，否则预热阶段将从摘要中排除。小型测试工具可能会因为增加 worker 而变慢；在将 worker 数量结果视为扩展性回归之前，请比较每个 worker 的数据包、字节和流预算。 ## 开发 运行 CI 使用的相同核心检查： ``` cargo fmt --check cargo test --all-targets --all-features cargo clippy --all-targets --all-features -- -D warnings cargo bench --bench packet_decode --no-run ``` 运行一个简短的端到端负载冒烟测试： ``` cargo run --release --bin wireprism-load -- \ --fixture http-requests \ --flows 10000 \ --workers 1,adaptive \ --runs 1 \ --warmups 0 ``` 解析器的更改应针对内置的协议语料库和至少一个真实的捕获进行验证。对性能敏感的更改应包括在同一台计算机上使用相同构建配置生成的前后报告。 ## 路线图 - 扩展每个解析器对畸形输入、分段和模糊测试的覆盖范围。 - 持久化捕获会话、收藏夹、隐藏规则和 UI 首选项。 - 在 Web UI 中扩展消息优先的导航和特定协议的视图。 - 添加超出 JSONL 的面向生产的存储和导出接收器。 - 以机器可读格式导出长时间运行的指标。 - 继续增加解析器深度和加密会话覆盖范围，同时不削弱内存界限或流正确性。 ## 安全性 捕获文件、负载、密钥日志、私钥和 JSONL 输出可能包含凭据或其他敏感数据。请将它们置于版本控制之外。仅捕获或解密您有权检查的流量。 ## 许可证 WirePrism 采用 [MIT 许可证](LICENSE) 授权。

标签：Rust, 可视化界面, 数据包抓取, 目录遍历, 网络流重组, 网络流量分析, 网络流量审计, 通知系统