finn-abel/MiniSniffer

# MiniSniffer MiniSniffer 是一个基于 libpcap 构建的小型 C 语言抓包器和网络分析器。 它可以捕获实时数据包（或读取 pcap 文件），解析常见的 IPv4/IPv6 链路层格式，应用过滤器，打印易读的摘要，解码 应用元数据，并可以将日志记录为 CSV/JSON 格式或报告捕获统计信息。 它是为学习、本地诊断和授权的网络 观测而构建的。它**不会**解密流量、注入或修改数据包，也**不会** 执行任何用于 MITM（中间人攻击）、凭据捕获、规避的操作，更**不能**在您不拥有或未获授权检查的网络上使用。 ## 核心亮点 - 使用 libpcap 进行实时捕获，或使用 `--read` 进行离线重放 / 使用 `--write` 将捕获保存为 pcap - 针对 TCP、UDP、ICMP/ICMPv6、ARP 等的 IPv4/IPv6 解析 - 协议、端口、主机、payload（文本/十六进制）和应用元数据过滤器 - 内核级 BPF 预过滤（仅用于优化；使用 `--no-bpf` 禁用） - 应用元数据解码：HTTP、DNS/mDNS、TLS ClientHello、DHCP 以及保守的 QUIC Initial - 有界限的 IPv4 分片和 TCP 流重组 - 人类可读的文本、JSON Lines (`--json`) 和 CSV (`--log`) 输出，以及 `--stats` 统计信息 ## 环境要求 - C11 编译器、`make` 和 libpcap | 平台 | 安装命令 | | --- | --- | | macOS (Homebrew) | `brew install libpcap pkg-config` | | Debian / Ubuntu | `sudo apt-get install build-essential libpcap-dev pkg-config` | | Fedora / RHEL | `sudo dnf install gcc make libpcap-devel pkgconf-pkg-config` | | Arch | `sudo pacman -S base-devel libpcap pkgconf` | 实时捕获需要提升的权限：使用 `sudo` 运行，或者在 Linux 上为 二进制文件授予 capabilities 而不是 root 权限： ``` sudo setcap cap_net_raw,cap_net_admin+eip ./MiniSniffer ``` ## 构建 ``` make # builds ./MiniSniffer make install # installs binary, man page, and shell completions (honors PREFIX/DESTDIR) make WITH_LIBIDN2=1 # optional: enables IDNA domain matching (--domain-match idna) ``` 构建时如果检测可用，将使用 `pkg-config` 来配置 libpcap，并回退到 `-lpcap`。如果您的工具链需要，可以在 `make` 命令行中覆盖 `CC`、 `CFLAGS`、`PKG_CONFIG` 或 `LDLIBS`。仓库内的 `packaging/homebrew/minisniffer.rb` 保留了 Homebrew formula，用于本地/`--HEAD` 安装（尚未发布到 tap）。 ## 快速开始 ``` sudo ./MiniSniffer --count 5 # 5 packets, default interface sudo ./MiniSniffer --interface en0 --count 5 # specific interface sudo ./MiniSniffer --protocol tcp --count 20 --stats # filter + summary stats sudo ./MiniSniffer --count 10 --log packets.csv # log to CSV sudo ./MiniSniffer --protocol tcp --payload --payload-contains "GET " # payload filter ./MiniSniffer --read capture.pcap --protocol tcp --count 10 # offline, no sudo needed ./MiniSniffer --list-interfaces # see available interfaces ``` 运行 `./MiniSniffer --help` 获取完整的选项列表，或运行 `man ./man/minisniffer.1` 查看每个 flag 的详细文档。 ## 过滤器 过滤器使用 **AND**（与）逻辑：当启用多个过滤器时，每一个都必须匹配， 数据包才会被显示、记录、计数或包含在统计信息中。`--count` 是在过滤*之后*应用的。 ``` sudo ./MiniSniffer --protocol tcp --port 443 --host 142.250.190.14 --count 10 sudo ./MiniSniffer --payload-hex "47 45 54 20" # matches "GET " sudo ./MiniSniffer --decode-app --app dns --dns-query example.com --dns-type A sudo ./MiniSniffer --decode-app --app tls --tls-sni example.com --tls-alpn h2 ``` `--protocol`、`--port` 和 `--host` 会被编译为内核级 BPF 过滤器， 这纯粹是为了优化；每一个显示的数据包仍然会在软件中重新检查， 而 `--no-bpf` 会禁用此功能。Payload 和应用层过滤器始终在 软件中运行。应用过滤器需要 `--decode-app`；添加 `--reassemble` 以 跨多个 TCP segment 对流进行分类。HTTP Host、DNS query 和 TLS SNI 过滤器默认使用规范化（不区分大小写）的域名匹配 — `--domain-match exact` 或 `idna` 可以更改此设置。 ## 输出 每个显示的数据包对应一行： ``` [001] TCP 192.168.1.25:51432 -> 142.250.190.14:443 size=54 [002] ICMP 192.168.1.25 -> 8.8.8.8 size=98 ``` `--payload` 会添加有界限的十六进制/ASCII 预览，`--decode-app` 会打印解码后的 应用元数据（状态为 `decoded`、`need_more`、`malformed`、 `truncated` 或 `no_match`），而 `--json` 会输出 JSON Lines 而不是文本。 `--log ` 写入 CSV。应用元数据在输出前会被转义，并且 CSV 单元格会中和电子表格公式字符。有关 JSON 对象结构和完整的 CSV schema，请参阅 man 手册页。 ## 开发 ``` make test # unit tests make check # tests + sanitizers + format-check + static-check make bench # lightweight local benchmarks make fuzz-smoke # replay fuzz corpora under ASan/UBSan make coverage # LLVM line + branch coverage make clean ``` 当 clang-format / clang-tidy / cppcheck 不可用时，`make check` 会跳过 格式/静态检查并输出提示消息。模糊测试工具位于 `fuzz/` 目录下（基于 libFuzzer，并为没有链接 libFuzzer runtime 的工具链提供了 独立的冒烟测试驱动程序）。GitHub Actions 工作流作为手动触发 （`workflow_dispatch`）的质量门禁包含在内。 ## 项目布局 ``` include/ Public headers fuzz/ Fuzzing harnesses + corpus src/ Implementation man/ Man page (minisniffer.1) tests/ Unit tests completions/ Bash, zsh, fish completions bench/ Local benchmarks packaging/ Packaging metadata docs/ Architecture docs Makefile Build/test/bench/fuzz/install ``` ## 文档 - [架构](docs/architecture.md) — 模块设计、重组模型和内部限制 - 手册页：`man ./man/minisniffer.1` - 完整的选项参考：`./MiniSniffer --help` ## 许可证 参见 [LICENSE](LICENSE)。 ``` ```

标签：协议解码, 客户端加密, 情报分析, 数据包解析, 目录遍历, 端点发现, 系统分析, 网络分析, 网络诊断