miasmaer/NULL
GitHub: miasmaer/NULL
NULL 是一个基于 libpcap 和 ncurses 构建的轻量级 Linux 命令行网络数据包嗅探器，提供实时协议解码与流量可视化。
Stars: 0 | Forks: 0
# *NULL* — 一个终端网络嗅探器
```
:::: ::: ::: ::: ::: :::
:┼:┼: :┼: :┼: :┼: :┼: :┼:
:┼:┼:┼ ┼:┼ ┼:┼ ┼:┼ ┼:┼ ┼:┼
┼#┼ ┼:┼ ┼#┼ ┼#┼ ┼:┼ ┼#┼ ┼#┼
┼#┼ ┼#┼#┼# ┼#┼ ┼#┼ ┼#┼ ┼#┼
#┼# #┼#┼# #┼# #┼# #┼# #┼#
### #### ######## ########## ##########
```
一个轻量级、仅限 root 的 Linux 命令行数据包嗅探器。*NULL* 使用 `libpcap` 捕获实时流量，进行足以实用的解码，并以实时滚动、彩色高亮的 `ncurses` 仪表盘或纯文本流的形式显示——同时提供可选的 CSV 日志记录功能。
## 目录
- [基本信息](#general-information)
- [安装](#installation)
- [可用参数](#available-arguments)
- [用法](#usage)
- [Bug 报告](#bug-reports)
- [许可证](#license)
- [免责声明](#disclaimer)
## 基本信息
*NULL* 是一个小巧、依赖极少的包嗅探器，直接基于 `libpcap` 和 `ncurses` 构建，不涉及任何其他第三方库。它旨在提供快速且易读的体验。
**核心功能：**
- **实时数据包捕获**：通过 `libpcap` 在立即模式下进行，具有可配置的快照长度和大型捕获缓冲区，可在繁忙的接口上实现低丢失率的捕获。
- **协议解码**：Ethernet（包括 802.1Q VLAN 标签）、ARP、IPv4、IPv6、TCP、UDP、ICMP、ICMPv6、IGMP、GRE、ESP、AH、SCTP 和 OSPF。
- **应用层检测**：
- **DNS** 查询名提取（从非响应数据包的第一个问题中提取）。
- **HTTP** 请求行和 `Host:` 头部解析（方法、路径、主机名）。
- **TLS** ClientHello SNI 提取（TCP 端口 443 流量）。
- **QUIC** 初始数据包 SNI 嗅探，因此也能显示 HTTP/3 主机名（UDP 端口 443 流量）。
- **两种显示模式**：全屏、彩色、可滚动的 `ncurses` TUI，或用于日志记录/脚本编写/无头机器的普通、可管道传输的文本流（`--no-color`）。
- **灵活的过滤**：捕获端 BPF 过滤器（端口、主机、原始 BPF 表达式）结合协议快捷方式（`--dns`、`--http`、`--https`/`--tls`、`--icmp`），以及硬性数据包计数限制。
- **CSV 导出**：导出每个匹配的数据包（时间戳、协议、地址、端口、长度、服务名称、主机名、HTTP 方法/路径），不限数量或限制为前 *N* 个数据包。
- **接口枚举**（`--list-interfaces`），因此您无需猜测设备名称。
- **干净关闭**：在 `Ctrl+C`/`SIGTERM` 时干净关闭，退出时会打印捕获和 CSV 的统计数据。
**项目结构：**
```
include/ Public headers (cli, sniffer, packet, csv_logger, tui)
src/ Implementation files, one per header, plus main.cpp
Makefile Build, install, debug, and run targets
```
## 安装
### 前置条件
- **Linux**（代码依赖于 `libpcap` 的 Ethernet 捕获、`netinet/*` 头文件和 `ncurses`；按照目前的编写方式，它无法移植到 Windows/macOS）。
- **Root 权限**（或二进制文件上的 `CAP_NET_RAW`/`CAP_NET_ADMIN`）——原始数据包捕获需要提升的访问权限。
- **支持 C++17 的编译器**（GCC 或 Clang）。
- **开发库**：`libpcap` 和 `ncurses`（头文件 + 链接库）、`make`。
### 安装构建依赖
选择适合您发行版的章节，然后按照下文描述进行构建。
**Debian / Ubuntu / Linux Mint / Pop!_OS / Kali:**
```
sudo apt update
sudo apt install -y build-essential libpcap-dev libncurses-dev
```
**Fedora:**
```
sudo dnf install -y gcc-c++ make libpcap-devel ncurses-devel
```
**RHEL / CentOS / Rocky Linux / AlmaLinux:**
```
sudo dnf install -y gcc-c++ make libpcap-devel ncurses-devel
# 在较旧的 RHEL/CentOS 版本上使用 yum：
sudo yum install -y gcc-c++ make libpcap-devel ncurses-devel
```
**Arch Linux / Manjaro / EndeavourOS:**
```
sudo pacman -Syu --needed base-devel libpcap ncurses
```
**openSUSE (Tumbleweed / Leap):**
```
sudo zypper install -y gcc-c++ make libpcap-devel ncurses-devel
```
**Alpine Linux:**
```
sudo apk add build-base libpcap-dev ncurses-dev
```
**Void Linux:**
```
sudo xbps-install -S base-devel libpcap-devel ncurses-devel
```
**Gentoo:**
```
sudo emerge --ask net-libs/libpcap sys-libs/ncurses
```
### 构建
该项目使用附带的 `Makefile` 进行构建——无需 CMake 或其他构建系统。目标文件会写入 `build/`，并具有自动依赖项跟踪，因此增量重建只会重新编译已更改的部分。
```
git clone https://github.com/miasmaer/NULL
cd null
make # builds ./null
```
其他 Makefile 目标：
```
make debug # rebuild from clean with -g -O0 -DDEBUG (for gdb/valgrind)
make run # build, then run with sudo
make install # install to /usr/local/bin/null
make uninstall # remove from /usr/local/bin
make clean # remove build/ and the null binary
```
在底层，`make` 使用以下命令编译每个 `src/*.cpp`：
```
g++ -std=c++17 -Wall -Wextra -O2 -Iinclude -MMD -MP -c .cpp -o build/.o
```
并使用以下命令进行链接：
```
g++ build/*.o -o null -lpcap -lncurses -pthread
```
（需要 `-pthread`，因为 TUI 在后台线程上运行捕获。）
## 可用参数
```
Capture options:
-i Interface to listen on (default: first active)
-p Filter by port number
--host Filter by source or destination IP
--filter "" Raw BPF expression (appended to built-in filter)
-c Stop after n packets
Protocol shortcuts:
--dns Show only DNS queries
--http Show only HTTP traffic
--https, --tls Show only HTTPS / TLS traffic
--icmp Show only ICMP packets
Display:
-v, --verbose Show extra detail (length)
--no-color Disable colours (also disables TUI)
Logging:
--sf [n] Save captured packets to a CSV file.
With a number, saves only the first n packets.
Without a number, saves all captured packets.
Utility:
--list-interfaces List capture interfaces and exit
-h, --help Show this help and exit
--version Print version and exit
```
注意：
- 协议快捷方式（`--dns`、`--http`、`--https`/`--tls`、`--icmp`）彼此之间使用 **OR** 逻辑组合，但所有这些都会与 `-p`、`--host` 和 `--filter` 执行 **AND** 运算。例如，`-p 8080 --http` 将捕获端口 8080 上**且**匹配 HTTP 快捷方式 BPF 子句的流量。
- `--sf` 后面不跟数字时会记录整个会话的所有匹配数据包；`--sf 500` 会在 500 个数据包后停止写入新的 CSV 行（捕获本身会继续，直到您退出或达到 `-c` 限制）。
- 很快会添加更多参数。
## 用法
原始捕获需要提升的权限，因此请使用 `sudo` 运行：
```
sudo ./null [options]
```
**示例：**
```
# 在 eth0 上嗅探 DNS 查询
sudo ./null -i eth0 --dns
# 在 wlan0 上嗅探 HTTPS/TLS 流量，并显示额外详细信息
sudo ./null -i wlan0 --https -v
# 监视自定义端口上的 HTTP 流量
sudo ./null -p 8080 --http
# 仅限来自/发往特定主机的数据包
sudo ./null --host 8.8.8.8
# 传递原始 BPF 过滤器并将捕获上限设为 100 个数据包
sudo ./null --filter "tcp port 22" -c 100
# 将前 500 个匹配的数据包记录到带时间戳的 CSV 文件中
sudo ./null --sf 500
# 将所有内容记录到 CSV，无上限
sudo ./null --sf
# Headless/纯文本输出，适合通过管道传递或记录到文件
sudo ./null -i eth0 --no-color > capture.log
# 列出可用的捕获接口
sudo ./null --list-interfaces
```
**TUI**（默认模式，除非传递了 `--no-color`）显示一个顶部栏（接口、过滤器、时钟），实时的协议计数“胶囊”（DNS/HTTP/TLS/UDP/ICMP/TCP/ARP/其他）以及总数据包和字节数，还有一个可滚动、彩色高亮的数据包表格（时间、协议、源地址、目标地址、服务以及主机名/HTTP/长度信息列）。
快捷键：
| 按键 | 操作 |
|-----------------|--------------------------|
| `q` / `Q` / `Esc` | 退出 |
| `↓` / `j` | 向下滚动一行 |
| `↑` / `k` | 向上滚动一行 |
| `Page Down` | 向下滚动一页 |
| `Page Up` | 向上滚动一页 |
| `g` / `Home` | 跳至顶部 |
| `G` / `End` | 跳至底部（最新）|
**CSV 输出**（`--sf`）会写入当前目录下的 `NULL_capture_YYYYMMDD_HHMMSS.csv` 文件，包含的列有：`time, proto, src_ip, src_port, dst_ip, dst_port, length, service, hostname, http_method, http_path`。
## Bug 报告
发现了崩溃、解析错误、您的发行版上的构建失败，或者在 TUI 中看起来不对劲的地方？请在本仓库中提一个 **GitHub Issue**。
在提交 issue 时，包含以下信息会有很大帮助：
- 您的发行版和版本。
- 编译器及其版本。
- 您运行的确切命令。
- 您期望发生的情况与实际发生的情况（包括任何错误输出）。
- 如果是捕获/解析的 bug，请提供相关的接口类型（如 Ethernet、Wi-Fi、VPN、容器桥接等）。
欢迎通过同一个 Issues 标签页提交功能请求和 pull request。
**注意**：如果您发现了安全问题，请前往 SECURITY.md 获取进一步的帮助。
## 许可证
该项目基于 **MIT 许可证**授权，完整文本请参见：[`LICENSE`](LICENSE)。
## 免责声明
本项目的创建者对其使用方式不承担任何责任。此工具仅用于研究、学习和授权的网络诊断。
您使用此软件的风险完全由您自己承担。您可以自由使用、复制、修改或基于此代码构建衍生项目，但任何此类项目**不得使用本项目的名称，且不得声称为本项目关联或受其认可**。
仅限在您拥有或获得明确监控权限的网络和接口上捕获流量。未经授权的数据包捕获在您所在的司法管辖区可能是非法的。
标签：网络协议分析, 网络抓包, 防御绕过