pcapflow
未知 pcap/pcapng 一条命令变真值基线：协议清单统计 + 流级索引（五元组、上下行统计、带置信度的标签）+ 每流一个 pcap（按协议分目录）。纯本地处理，不上传任何数据。
用途
把一个未知抓包变成可测试的真值基线，典型任务：
- 流量检测设备测试（探针 / NIDS / NPM / DPI）：从 pcap 提取协议检出清单、每流五元组与上下行报文字节数，作为设备比对基准（本工具只做真值侧，设备比对不在此范围）；
- 未知抓包摸底：快速回答"这个 pcap 里有什么协议、多少条流、谁最大"；
- 按流拆包：把混合流量按流切成单流 pcap，且按协议分目录、五元组命名，可直接用 Wireshark 逐流检查；
- 半途抓包 / 端口复用 / IP 分片 / IPv6 / TLS/QUIC SNI / 加密流熵等复杂形态已在标签规则中显式处理（见
references/labeling-rules-v1.1.md）。
快速开始
前置：Python 3.9+、已安装 Wireshark（或独立 tshark）4.4.x、pip install dpkt==1.9.8。
cd pcapflow # 进入本 skill 目录（含 pcapflow.py）
python3 pcapflow.py --check-env # 环境自检（tshark 定位/dpkt/编码）
python3 pcapflow.py your_capture.pcap # 分析任意 pcap/pcapng
cat your_capture_flows/protocols.csv # 查看协议清单
注：本分发包不含 .pcap 样例（发布平台文件类型限制）；examples/expected/ 预期
输出对照仍随包提供。样例 pcap、make_demo.py 复现与全量自测
（bash scripts/selfcheck.sh，样例缺失时自动降级为环境自检 + 单元测试）请在完整
源仓库中运行；使用 pcapflow 本身只需任意自己的 pcap。
输入输出
输入：任意 pcap / pcapng 文件（以太链路，IPv4/IPv6，微秒精度；pcapng 进度百分位退化为纯计数）。
输出（默认 <pcap名>_flows/，可用 -o 指定）：
examples/demo_flows/
├── flows.csv # 流级索引，每流一行（20 列）
├── protocols.csv # 协议清单统计 + TOTAL 行
└── flows/<协议>/ # 单流 pcap：{src}_{sport}_{dst}_{dport}_{transport}_{stream_id}.pcap
flows.csv 关键列：stream_id、五元组（src_ip/src_port/dst_ip/dst_port/transport）、
app_primary（协议标签，如 http / tls/https / dns / quic / unknown_encrypted）、
label_state、first_data_label、integrity（complete/mid-capture/unknown）、
confidence、up_pkts/up_bytes/down_pkts/down_bytes、first_ts/last_ts/duration、
evidence（证据链）、pcap_path。完整 20 列字典与 CSV 契约见 references/cli-reference.md。
参数
| 参数 | 说明 |
|---|---|
pcap |
输入 pcap/pcapng 路径（位置参数） |
-o OUTDIR |
输出目录（默认 <pcap名>_flows） |
--check-env |
仅环境自检（tshark 定位 / dpkt / 编码 / 临时目录写权限） |
--no-split |
只出索引 CSV，不切单流 pcap（pcap_path 列留空） |
--top N |
控制台摘要 Top-N 大流提示（默认 10，0 关闭） |
--max-fd N |
单流 pcap 句柄池上限（默认 256；高并发流场景调大） |
-V |
显示版本 |
tshark 定位链（优先级从高到低）：环境变量 TSHARK_BIN（精确二进制路径）→ WS_HOME（Wireshark 根目录）→ PATH → Windows 注册表 → 默认安装路径。退出码：0 成功；1 失败（含切流帧数校验失败）。
边界与依赖
- 依赖：Python 3.9+；tshark 4.4.x（GPLv2 程序，仅作独立子进程调用，不随包分发、不构成衍生——字段输出契约以 4.4.x 为准，3.x 有布尔/十六进制差异）；dpkt 1.9.8（BSD-3，pip 声明式依赖）。
- 范围边界：只做真值提取，不含设备端比对/检测率计算；加密流只做定性（SNI/ALPN/熵），不解密内容。
- 性能边界：帧级索引全内存，百万帧级 pcap 内存约数百 MB；大流场景建议
--max-fd 512。 - Windows：兼容层（四级 tshark 定位 / 编码兜底 / 文件名安全化 / 长路径守卫）+ 跨平台一键入口
run.py（自动 UTF-8 输出，首跑即--check-env），静态防御已备，真机冒烟待社区反馈；离线部署指南见references/windows-deploy.md。 - 已知局限：A0(keep-alive) 判定依赖 tshark 字段（未做 dpkt 侧 seq 复核）；隧道流量仅标注
tunnel状态不拆双标签；超长抓包 IP id 回绕按首见优先。 - 规则依据：流级标签裁决（P1/P2/P3/P4-lite 分级、A0–A4 帧分类、承载折叠、分母保护）完整规范见
references/labeling-rules-v1.1.md；架构与两遍扫描流水线见references/architecture.md。
