zer0contextlost/pcapr

# PCAPR **从网络捕获中进行协议逆向工程。** · v0.6.0 为 PCAPR 提供一个 `.pcap` 文件，它会自动发现消息成帧、字段布局和字段语义（魔术字节、长度字段、操作码、校验和、标志位、时间戳）。它还会检测安全指标：C2 信标、TLS 指纹 (JA3)、DNS 隧道、ECB 模式弱加密和 XOR 混淆流。 在任何命令后添加 `--learn` 即可获得每一项发现的纯英文解释 —— 专为学习网络取证的人士打造。 ## 安装 ``` # 推荐 — 使用锁定 deps 进行可重复安装 uv sync # 或者使用 pip pip install -e . ``` 需要 Python 3.11+。通过 `pip install uv` 或从 [astral.sh/uv](https://astral.sh/uv) 安装 `uv`。 ## 快速开始 ``` # 分析捕获数据 — 自动选择最繁忙的端口 pcapr capture.pcap # 固定到特定端口，生成 HTML 报告 pcapr capture.pcap --port 4444 --html report.html # 学习模式 — 用纯英文解释为每个发现添加注释 pcapr capture.pcap --learn pcapr capture.pcap --learn --html report.html # 显示所有端口上的活动协议 pcapr capture.pcap --overview # 探测实时服务 pcapr --probe 10.0.0.1:4444 # 实时捕获（在 Windows 上需要管理员权限 / Npcap） pcapr --live eth0 --port 4444 --duration 30 # 解释字节 0 被如此分类的原因 pcapr capture.pcap --explain 0 # 生成 Wireshark Lua 解码器 pcapr capture.pcap --lua dissector.lua # 生成 Kaitai Struct schema pcapr capture.pcap --kaitai protocol.ksy # 生成并立即针对目标运行 boofuzz pcapr capture.pcap --fuzz 10.0.0.1:4444 ``` ## 安全检测 PCAPR 在每次捕获时都会自动运行安全分析。 ### 信标 / C2 检测 标记消息间时间间隔异常规律的数据流 —— 这是 C2 植入、键盘记录器和计划数据渗漏的典型特征。使用仅在每方向、周期间隔上计算的变异系数（CV = 标准差/平均值）（忽略突发内噪音）。 ``` 2 beaconing stream(s) detected: 10.2.28.88 -> 45.131.214.85 interval=60.1s CV=0.001 [highly regular] direction=server ``` 针对具有记录在案的 60 秒信标间隔的真实 NetSupport RAT 捕获进行了验证。 ### JA3 TLS 指纹识别 当检测到 TLS 时，从 ClientHello 消息中提取 JA3 哈希 —— 这是 TLS 客户端实现的指纹。无论服务器是什么，相同的恶意软件家族都会生成相同的 JA3 哈希。可以在公共威胁情报源中查找这些哈希。 ``` 1 unique JA3 fingerprint(s): 839bbe3ed07fed922ded5aaf714d6842 SNI=example.com ``` 哈希值已对照 `jabedude/ja3-rs` 测试套件进行了验证（Firefox，curl 完全匹配）。 ### DNS 隧道检测 检测通过 DNS 进行的数据渗漏。根据以下方面对每个 DNS 数据流进行评分：查询名称熵、唯一子域名多样性、长名称比率和超大响应。分数超过 30% 的将被标记。 ``` DNS tunneling suspected (score=44%): - 222 unique subdomains out of 222 queries ``` 针对 Elastic iodine 样本捕获进行了验证。 ### XOR 密钥恢复 (`--try-xor`) 使用熵过滤（跳过明文和真正的随机数据）检测 XOR 混淆流，并恢复重复密钥。在逐位置暴力破解之前，使用重合指数法对可能的密钥长度 1-16 进行排序 —— 能够捕获简单的 1/2/4 字节扫描所遗漏的 3、5、6 和 7 字节密钥。存储完整的解密流。 ``` 1 XOR key(s) recovered: key=0x42 entropy 6.81 -> 3.12 (drop 3.69) ``` 使用 `--xor-out DIR` 将每个恢复的流写入 `DIR/stream__.bin`。 ### ECB 模式检测 自动扫描所有高熵流以查找重复的 AES-ECB（16 字节）或 3DES-ECB（8 字节）块模式。ECB 模式独立加密每个块 —— 相同的明文块产生相同的密文，即使没有密钥也会泄露结构。在终端和 HTML 报告中均标记为安全发现。 ``` ECB MODE DETECTED (1 stream — identical plaintext blocks leak as identical ciphertext) AES-ECB stream 10.0.0.1:4444->10.0.0.2:52110 12 repeated / 48 total blocks (25% repeat rate) ``` ### Ciphey 集成 (`--try-ciphey`) 将包含大量文本的流通过管道传递给 [Ciphey](https://github.com/bee-san/Ciphey)，以进行经典密码和多层数据编码检测 —— Caesar、Vigenère、Beaufort、ROT13、链式 base64 等。补充了内置的二进制解码器（zlib/gzip/base64/hex）：Ciphey 处理文本密码，PCAPR 处理二进制编码。 ``` pip install ciphey # one-time install pcapr capture.pcap --try-ciphey ``` 如果 Ciphey 不在 PATH 中，将优雅地跳过并提示安装方法。 ### 异常评分 每条消息都会根据以下方面进行评分：熵峰值、大小异常值（Tukey 栅栏）、未知操作码值、状态机违规和文本注入模式（SQLi、路径遍历、XSS、命令注入）。高分消息将以带有颜色编码的异常卡片形式显示在 HTML 报告中。 ## 学习模式 (`--learn`) `--learn` 使用纯英文解释对终端输出和 HTML 报告进行注释。专为取证学生和从零开始培养数据包分析技能的人员设计。 **解释内容包括：** - 协议识别的工作原理（端口 + 字节证据、置信度分数、低于阈值时的最佳猜测推理） - 什么是成帧以及检测到的类型（分隔符 / 长度字段 / 变长整数） - 编码与加密 —— 在分析前剥离编解码器时该怎么做 - 负载熵对分析人员的意义（明文 / 压缩 / 加密阈值） - 什么是信标以及为什么即使没有解密 CV 也能使其可检测 - XOR 混淆：重合指数法的作用及其原理 - ECB 模式弱点：为什么相同的明文块会产生相同的密文（ECB 企鹅类比） - Ciphey 结果：什么是经典密码（Caesar、Vigenère、ROT13）以及它们何时出现 - 明文敏感数据：为什么被动 Wi-Fi 嗅探很危险 - 威胁情报：什么是 JA3 哈希源以及如何解释命中（是线索，而非最终定论） - 流量分类：流量配置文件标签的含义 - 状态机推断：它告诉你什么以及为什么它对模糊测试很重要 - 每个操作码分析：为什么相同的字段在不同的消息类型中可以有不同的结构 - TLV 检测：什么是类型-长度-值编码（ASN.1、MQTT、蓝牙示例） - 每种字段类型的词汇表：MAGIC、LENGTH、TYPE_ENUM、SEQUENCE、FLAGS、CHECKSUM、TIMESTAMP、ECHO、IPv4、UUID、STRING 在 HTML 报告中，解释以可折叠的 `

` 元素形式出现 —— 不需要它们的分析人员可以完全忽略它们。 ## PCAPR 学院 (`pcapr-serve`) 本地分析控制台在 `/academy` 路径下包含一个内置的挑战课程。 ``` pcapr-serve # start the server # 打开 http://127.0.0.1:7742/academy ``` **跨越 3 个级别的 11 项结构化挑战：** | 级别 | 挑战 | 学到的内容 | |------|-----------|----------------| | 1 | FTP: 明文凭证 | 明文协议，敏感数据检测 | | 1 | HTTP: 带凭证的表单 POST | HTTP 成帧，POST 正文分析 | | 1 | DNS: 查询和响应结构 | 二进制固定报头成帧，事务 ID | | 1 | ICMP: 回显请求 / 回复 | 最简单的二进制协议，echo/sequence 字段 | | 1 | Telnet: 明文远程终端 | 分隔符成帧，明文终端数据 | | 2 | MQTT: IoT 发布 / 订阅 | 二进制长度前缀成帧，操作码枚举 | | 2 | Redis: RESP 协议 | 文本协议，批量字符串成帧 | | 2 | TLS: ClientHello 和 JA3 指纹识别 | TLS 握手，JA3 提取 | | 2 | Modbus TCP: 工业控制协议 | MBAP 报头，功能码，无身份验证的 OT 风险 | | 3 | XOR 混淆: 密钥恢复 | 基于重合指数的密钥长度估计，熵降 | | 3 | AES-ECB 模式: 密文结构泄露 | 块重复，ECB 弱点 | 每项挑战都展示了目标、可折叠提示和一个一键式的 **Analyze** 按钮，该按钮会以 `--learn` 模式运行完整的流程。进度在重启后依然保留。 将挑战用的 pcap 放在 `~/.cache/pcapr/academy/pcaps/` 中 —— 有关每个挑战的精确 Wireshark 捕获说明，请参见 `ACADEMY_PCAP_WISHLIST.md`。 ## 输出格式 | 标志 | 格式 | 用例 | |------|--------|----------| | *(无)* | 终端 (Rich) | 交互式探索 | | `--html FILE` | HTML | 分享、存档、`--learn` 注释 | | `--json` | JSON | 脚本编写，后处理 | | `--kaitai FILE` | Kaitai Struct | 解析器生成 (Java, Python, C++, …) | | `--lua FILE` | Wireshark Lua | 实时捕获解析 | | `--scapy FILE` | Scapy 层 | Python 工具集成 | | `--fuzz-dict FILE` | AFL/libFuzzer 字典 | 结构感知的模糊测试 | | `--boofuzz FILE` | boofuzz 脚本 | 网络模糊测试 | | `--client-py FILE` | Python 客户端 | 独立的协议客户端 | ## CLI 参考 ### `pcapr` —— 单文件或实时分析 ``` pcapr [OPTIONS] [PCAP_FILE] PCAP_FILE .pcap or .pcapng file to analyze Analysis options: --port, -p INTEGER Filter to a specific port --gap FLOAT Message boundary gap in seconds [default: 0.05] --min-messages INTEGER Minimum messages per stream [default: 5] --overview Print traffic overview table and exit --flag-outliers Score messages for anomalies and report suspicious ones --explain BYTE Print field evidence for byte offset BYTE --learn Annotate report with plain-English explanations Output options: --html FILE Write self-contained HTML report --json Write JSON to stdout --lua FILE Write Wireshark Lua dissector --scapy FILE Write Scapy Packet subclass --kaitai FILE Write Kaitai Struct .ksy spec --fuzz-dict FILE Write AFL/libFuzzer keyword dictionary --boofuzz FILE Write boofuzz fuzzer script --fuzz HOST:PORT Generate and run boofuzz fuzzer immediately --client-py FILE Write standalone Python protocol client Live capture: --live IFACE Capture from interface (requires admin/Npcap) --duration FLOAT Capture duration in seconds [default: 30.0] --save-pcap FILE Save live capture to file --window FLOAT Print preliminary analysis every N seconds [default: 10.0] Encryption analysis: --try-xor Attempt XOR key recovery on high-entropy streams --xor-out DIR Write recovered XOR streams to DIR/stream__.bin --try-ciphey Pipe text-heavy streams to Ciphey (requires: pip install ciphey) --sslkeylog FILE Decrypt TLS sessions via SSLKEYLOGFILE (TLS 1.2 and 1.3) Probing: --probe HOST:PORT Connect and characterize the service ``` ### `pcapr-diff` —— 比较两次捕获 ``` pcapr-diff PCAP_A PCAP_B [--port INTEGER] [--html FILE] ``` 比较同一协议的两次捕获之间的熵、字段布局、方向比和每个操作码的熵。对于检测跨固件版本或 A/B 测试配置的协议更改很有用。 ### `pcapr-replay` —— 重放捕获的会话 ``` pcapr-replay PCAP_FILE --target HOST:PORT [OPTIONS] --mutate Apply mutation strategies (fuzz) --save-responses Write server responses to a pcap --udp Use UDP instead of TCP ``` 在重放之前自动修补动态字段：序列计数器、时间戳、长度字段、校验和和 echo（事务 ID）字段。 ### `pcapr-batch` —— 分析多个捕获 ``` pcapr-batch PCAP_FILES... --out-dir DIR [--port INTEGER] ``` 为每个捕获生成一份 HTML 报告，并生成一个带有熵着色和跨捕获差异比较链接的 `index.html`。 ### `pcapr-serve` —— 本地 Web UI ``` pcapr-serve [--port 7742] [--bind 127.0.0.1] ``` 拖放上传、SHA-256 去重、缓存报告、浏览器内跨捕获差异比较。打开 `http://127.0.0.1:7742`。 ## PCAPR 能推断出什么 **成帧 (Framing)** - 基于分隔符（`\r\n`、`\x00`、自定义字节序列） - 长度字段（1/2/4 字节大端序或小端序前缀） - 变长整数（LEB128、MQTT 样式） - ASCII 长度前缀（njRAT/Xworm 样式：十进制数字 + 分隔符） **字段类型** - `magic` —— 常量前缀字节（协议签名） - `length` —— 编码消息或正文大小 - `type_enum` —— 操作码 / 消息类型（较小的不同值集合） - `sequence` —— 单调递增的计数器 - `echo` —— 从请求镜像到响应中的值（事务 ID） - `flags` —— 位掩码；分解为位级别的子字段 - `checksum` —— 对前述字节计算的 CRC32/CRC16/sum8/sum16 - `timestamp` —— Unix 纪元或类似的时间值 - `ipv4` —— 嵌入在负载中的原始 4 字节地址 - `uuid` —— 128 位 GUID - `string` —— 带有长度前缀或以空字符结尾的 **编码检测** 检测并剥离负载中的 zlib、gzip、zstd、lz4、base64 或 hex 编码，然后重新分析内部协议。 **语义注释** 在字段推断之后，使用真实的语义升级推断出的字段：CRC 验证、时间戳范围检查、IPv4 格式验证、字符串边界检测。 ## USB 设备流量 PCAPR 读取来自 Linux USBMon（`tshark -i usbmon0`，Linux 上的 Wireshark）和 Windows USBPcap（Windows 上的 Wireshark）的 USB 设备捕获。它按端点对流量进行分段，推断字段结构，并对常见的 USB 设备类进行指纹识别。 **支持的 USB 类：** - **USB HID** —— 键盘/鼠标启动协议中断报告（3、4 或 8 字节固定大小的报告） - **USB CDC** —— 串口转 USB：来自调制解调器的 AT 命令流量，串行适配器 - **USB 大容量存储 (BOT)** —— SCSI 仅批量传输（`USBC`/`USCS` 魔术字节） ``` # 分析 USB 捕获数据 — 支持 .pcap 和 .pcapng pcapr usb_device.pcap # 聚焦特定端点 pcapr usb_device.pcap --port 1 # EP 0x01 # 生成 pyusb 客户端（需要 pip install pyusb） pcapr usb_device.pcap --client-py client.py ``` 生成的 `--client-py` 输出使用 `pyusb`（`usb.core.find(idVendor, idProduct)`）而不是套接字。提供您设备的 VID:PID —— 在 Linux 上使用 `lsusb` 或在 Windows 上使用 USBDeview 来查找它。 **捕获命令：** ``` # Linux: 从 usbmon 捕获（需要 usbmon 内核模块） sudo modprobe usbmon tshark -i usbmon0 -w usb_capture.pcap # Windows: 使用安装了 USBPcap 的 Wireshark，或通过 USBPcap CLI 捕获 USBPcapCMD.exe -d \\.\USBPcap1 -o usb_capture.pcap ``` ### JTAG 和 UART JTAG 和 UART 捕获使用逻辑分析仪格式（Sigrok `.sr`，Saleae `.logicdata`），这超出了 pcap 模型的范围。如果有社区需求，我们将添加支持 —— 如果您需要，请提出 issue。 ## 安全研究用例 - **恶意软件 C2 分析** —— 放入一个未知 C2 流量的捕获；在几秒钟内获得字段布局、操作码枚举、信标间隔和 Wireshark 解析器 - **TLS 客户端指纹识别** —— 提取 JA3 哈希并与威胁情报进行交叉比对 -DNS 渗漏检测** —— 对 DNS 流量进行隧道特征评分 - **模糊测试** —— 生成结构感知的 AFL/libFuzzer 词典；使用 `--mutate` 重放来探测实时目标 - **协议审计** —— 在固件更新前后使用 `pcapr-diff` 检测更改 - **CTF** —— 无需手动使用 Wireshark 即可快速适应二进制协议挑战 - **取证学习** —— `--learn` 模式解释每一项发现；可与任何真实的捕获一起使用 ## 真实基准测试 针对带有第三方标签的捕获运行测试 —— 而不是针对为了匹配实现而构造的数据运行。 | 测试 | 来源 | 验证内容 | |------|--------|-----------| | PPA FTP, Telnet, HTTP, DNS, email | Practical Packet Analysis (Sanders, No Starch Press) | 协议识别 | | JA3 Firefox, curl | `jabedude/ja3-rs` 测试套件 (assert_eq! 已验证的哈希) | JA3 指纹识别 | | DNS 隧道 (iodine) | Elastic 示例仓库，已确认的 iodine 会话 | DNS 隧道检测 | | NetSupport RAT 信标 | GitHub 恶意软件分析项目，记录在案的 60 秒间隔 | 信标检测 | ``` pytest tests/test_ground_truth.py -v ``` ## 许可证 Apache 2.0 —— 参见 [LICENSE](LICENSE)。

标签：boofuzz, C2检测, DNS隧道, IP 地址批量处理, JA3, Kaitai Struct, Lua解析器, PCAP解析, Python, Radare2, Scapy, TLS指纹, Wireshark, XOR解混淆, 信标检测, 协议字段推断, 句柄查看, 多架构支持, 安全报告, 弱加密检测, 无后门, 模糊化, 流量监控, 网络协议逆向工程, 网络安全, 网络抓包, 自动化分析, 解码器, 跨站脚本, 隐私保护