esandeepchoudary/pcap-vis-anz

# PCAP 网络可视化工具 一款交互式的基于 Web 的网络抓包可视化工具。上传 `.pcap`、`.pcapng` 或 `.cap` 文件，将你的网络探索为动态的力导向图 —— 包含主机分类、协议检测、OS 指纹识别和 DNS 解析。专为 SOC 分析师、OT/ICS 与 IoT 安全工程师，以及任何需要快速将原始抓包转化为可检查网络地图的网络取证或事件响应人员而构建。 [](https://www.python.org/) [](https://flask.palletsprojects.com/) [](./LICENSE) [](https://esandeepchoudary.github.io/pcap-vis-anz/) ## 目录 - [文档](#documentation) - [功能](#features) - [异常检测](#anomaly-detection) - [OT/ICS 协议支持](#otics-protocol-support) - [IoT 设备支持](#iot-device-support) - [环境要求](#requirements) - [安装说明](#installation) - [使用说明](#usage) - [捕获你自己的流量](#capturing-your-own-traffic) - [项目结构](#project-structure) - [测试](#testing) - [配置](#configuration) - [安全性与自包含](#security--self-containment) - [故障排除](#troubleshooting) - [许可证](#license) ## 文档 完整的教程（附带真实截图）和产品文档发布在 **[esandeepchoudary.github.io/pcap-vis-anz](https://esandeepchoudary.github.io/pcap-vis-anz/)** —— 涵盖了每个视图（Graph、Table、DNS Map、OT Map、OT Log、VLAN、Diff、Dashboard、Findings）以及概述、快速入门指南和配置参考。该文档站点还提供了一个供基于 LLM 的工具使用的 [`llms.txt`](https://esandeepchoudary.github.io/pcap-vis-anz/llms.txt) 索引。 如果你是在此仓库中工作的编程代理，请参阅 [`AGENTS.md`](./AGENTS.md) 了解分支约定、测试工作流和架构图 —— 它是权威的最新参考（`CLAUDE.md` 仅指向它）。在运行中的实例上访问 `GET /session-schema` 也会返回一个描述 `/upload` 响应结构的真实 JSON Schema，如果你正在对接 API 而非阅读 UI，这将非常有用。 ## 功能 ### 可视化与图表 - **交互式图表** — 基于 D3.js v7 力导向模拟，包含 Force、Radial 和 Cluster 布局模式；支持拖拽、缩放和平移 - **详情面板** — 点击任意节点查看主机详情（端口、服务、流量统计、DNS 查询、TLS SNI 名称、异常、OT 分析、会话以及捕获的凭证）；IP、主机名、JA3 指纹和 SHA-256 哈希值旁边提供安全复制按钮 (⧉) - **色盲友好调色板** — 图表控件中的 ◑ 按钮可将所有节点和边缘颜色切换为适合绿色弱视人群的调色板（绿色 → 青色，红色 → 橙色）；设置持久化于 localStorage - **统计迷你图** — Packets 统计数据旁边有一个 48×12 像素的内联 SVG 条形图，显示整个抓包持续时间的包密度分布 - **增强型右键菜单** — “Highlight Anomalies” 会使所有非异常节点淡化，以便立即专注于分诊；“Open in Table” 会切换到预过滤为该节点 IP 的连接表 - **时间轴** — 双滑块刷子，用于选择任意时间窗口（拖动两端调整大小，拖动蓝色选区移动）；自动播放会将窗口向前滑动；速度选择器（0.5×、1×、2×、5×）；abs/rel 切换开关用于在 `HH:MM:SS–HH:MM:SS` 和 `+Ns–+Ns` 之间切换；空格键播放/暂停，←/→ 移动窗口 - **图表高级功能** — 节点固定（选中节点 → 按 P；黄色虚线环；拖动以重新定位；右键 → Unpin All）；隔离模式（双击节点仅显示它及其直接邻居；再次双击恢复）；小地图（150×100 概览，右下角，拖动以平移）；悬停时显示边缘数据包计数标签；键盘快捷键叠加层（按 ?）；**集群折叠**（⊕ 按钮进入集群模式 — 点击侧边栏中的任何主机类型标签，将折叠该类型为一个质心芯片，点击芯片重新展开） ### 视图 - **九大视图** — Graph（网络地图）、Table（可排序的连接列表）、DNS Map（查询浏览器）、OT Map（Purdue 模型区域布局）、OT Log（按时间顺序排列的 OT 命令历史）、VLAN Graph（VLAN 分段拓扑）、Diff（基线比较）、**Dashboard**（摘要卡片、风险评分条形图、协议分布、可点击的 Top Anomalies 列表；快捷键 `8`）以及 **Findings**（分析师分诊工作区；快捷键 `9`） - **Findings 工作区** — 自动从异常、捕获的凭证、文件传输、OT 写入/错误命令组和高风险主机中推导出可审查的发现；支持状态、严重性覆盖、分析师备注、报告纳入/排除、证据复制包、图表/数据包导航以及误报抑制。 ### 主机、协议与网络检测 - **主机分类** — 38 种主机类型：路由器、PLC、IP 摄像头、Web 服务器、DNS 服务器、Windows 主机等 - **协议检测** — 通过端口识别 80 多种协议（HTTP、SSH、DNS、RDP、MySQL、Modbus、MQTT、CoAP 等） - **IPv4 和 IPv6 支持** — 同时跟踪两个地址族；正确分类私有范围（包括 IPv6 回环、ULA 以及完整的 `fe80::/10` 链路本地范围）；IPv6 节点以虚线环显示；当两个地址族同时存在时，会出现头部采用统计（`IPv6: X% (N/total)`）；侧边栏 **IP Version** 过滤器（仅在混合抓包中显示）；IPv6 扩展头部（逐跳、路由、目标选项、分片、AH）被逐一穿透，因此即使存在扩展头部，也能正确识别 TCP/UDP 端口 - **OS 指纹识别** — TTL / 跳数限制启发式方法（Linux/Unix、Windows、网络设备） - **MAC 厂商查询** — 涵盖 IT、OT 和 IoT 厂商的 OUI 查询（VMware、Cisco、Siemens、Amazon Echo 等） - **DNS 名称解析** — 从捕获的 DNS 流量中提取主机名和查询日志 ### VLAN - **VLAN 识别** — 完整的 802.1Q 单标签和 QinQ 双标签解析（同时支持 802.1ad `0x88A8` 外层 TPID 形式以及一些较旧的 Cisco `dot1q-tunnel` 部署使用的传统堆叠 `0x8100`/`0x8100` “标签嵌套”形式）：提取 VLAN ID、PCP 优先级位、DEI 位以及 QinQ 的外部/内部 VIDs；按主机、按连接进行跟踪，并在统计中进行汇总。 - **VLAN Graph 视图** — 专用标签页，将 VLAN 显示为带有凸包集群多边形的超级节点；主机在内部集群化；多 VLAN（跳跃）主机物理放置在网段之间；跨 VLAN 流量显示为红色边缘；VLAN 间网关节点标有 GW 徽章；**主机节点现在显示与主 Graph 视图相同的主机类型 emoji 图标**（🌐 Web 服务器，⚙️ PLC，📷 IP 摄像头等） - **VLAN 安全分析** — 分段得分（0–100，附带 Good/Fair/Poor/Critical 评级）、按 VLAN 进行 ARP 欺骗检测、广播风暴检测（>10% 广播阈值）、PCP 优先级滥用检测；4 条 VLAN 异常规则（跳跃、原生泄漏、QinQ、跨段 OT） - **VLAN 数据丰富** — VLAN 到子网的映射、CDP/LLDP 帧解析（从 Cisco Discovery Protocol 和 IEEE 802.1AB 交换机帧中提取设备主机名和原生 VLAN）、按 VLAN 汇总的风险得分、VLAN 蔓延指标（单例/隔离的 VLAN） - **VLAN 导出** — VLAN 清单 CSV（每个 VLAN 的每个主机 14 列）、VLAN 流量 CSV（包含源/目的 VLAN 和跨 VLAN 标志）、VLAN 图表 SVG、VLAN 矩阵 PNG（当前视图或所有 4 个视图依次导出，每个视图带有标题/图例条带）、Markdown 审计报告中的 VLAN 部分、VLAN 名称 CSV 导入 - **VLAN 用户体验** — 主图表中的按 VLAN 着色切换、VLAN 标签页工具栏中的 VLAN 搜索、用户分配的 VLAN 标签（双击重命名，持久化于 localStorage）、侧边栏中的 VLAN 健康摘要卡片、⊞ 矩阵视图（VLAN×VLAN 流量邻接网格）、VLAN 聚焦（一键过滤主图表至单个 VLAN）、⊕ Diff 视图中的 VLAN 更改检测列、按 VLAN 带宽堆叠的时间轴小地图 - **VLAN 流量矩阵 — 4 种视图** — ⊞ 矩阵切换现在提供了一个分段切换器，包含四种模式：**Traffic**（单元格亮度 = 对数缩放的流量，带有 Bytes | Packets 子切换和单元格内总计）、**OT/ICS**（承载 OT/ICS 协议流量的 VLAN 对上的橙色热力图，当 OT 写入跨越边界时单元格边框为橙色，对于有流量但无 OT 的对显示为灰色）、**Anomalies**（单元格颜色 = 跨所有异常类型的最严重程度 — 不仅仅是跨段 OT — 带有单元格内异常计数；像端口扫描这样的单主机异常落在对角线上），以及 **Protocol**（每对的主要协议，带有列出显示的每种协议颜色以及跨 VLAN OT 异常色块的图例）。每种模式都有自己的悬停提示和图例。单元格归属现在使用每个主机的**完整 VLAN 成员身份**（不仅仅是它的第一个 VLAN），与 VLAN 图表视图的跨链接提示中显示的总数相匹配 — 多 VLAN 主机会计入每个成员身份对。单元格大小会缩放以填满可用的面板宽度（对于 ≤20 个 VLAN，每个单元格最大 110px），小型（少 VLAN）矩阵会居中显示，而不是停留在左上角。每个视图都可以通过工具栏的 **⤓ PNG** 按钮导出为自描述的高分辨率 PNG（带有标题头 + 图例页脚条带，无论显示器如何，最低 2x 像素密度）（Shift 点击，或全局导出菜单中的“…(all views)”项，依次导出所有四个视图） - **文件传输下载** — 直接从 File Transfers 侧边栏面板下载 PCAP 中捕获的 HTTP 文件（大小受限的 LRU 内存缓存，上限 256 MB，下载链接在后续上传后依然保留） ### OT/ICS - **OT Map** — 完整的 Purdue 模型泳道视图（L0 Field → L6 Public Internet），对于非 RFC1918 IP 自动生成 Public Internet 区域（无需 GeoIP），支持 D3 缩放/平移（Ctrl+滚动，工具栏按钮），流量加权边缘，异常标注（受影响节点上的 ! 徽章，高严重性泳道染色），跨区域与跨层级边缘计数，区域图例，Purdue 层级提示，与侧边栏 bypass 切换（“Respect filters”按钮）集成的 activeTypes 过滤，基于 OT 协议证据的 Purdue 层级分配，以及可编辑模式：拖拽以重新分类、添加/移除设备（IP 格式 + Purdue 层级验证及内联错误）、风险标注（Critical → Info，面板位于点击节点附近），以及 PNG/JSON 导出 - **OT 通信矩阵** — OT Map 视图内的切换开关（⊞ Matrix 按钮），用于切换到设备×设备邻接矩阵：每个单元格按主要的 OT 协议着色，跨区域流量为橙色，存在异常时为红色边框；悬停查看数据包计数、字节总数、OT 读/写计数以及跨区域/异常警告。单元格大小适应可用的面板宽度（根据设备数量进行限制，镜像 VLAN 矩阵），小矩阵居中而不是固定在左上角，并且网格会在窗口调整大小时重排 - **OT 分析面板** — 按节点显示读/写/错误比例条、主站/子站角色徽章、Modbus 单 ID、DNP3 链路地址 ### 安全与取证 - **TLS 检查** — 解析 TLS ClientHello 以提取 SNI（服务器名称）并计算 JA3 指纹；与精选的已知恶意 JA3 列表匹配，以标记恶意软件/C2 TLS 会话 - **凭证提取** — 从 HTTP Basic Auth、HTML 表单 POST、FTP、Telnet、MQTT CONNECT 和 CoAP 捕获明文凭证；在侧边栏显示，带有密码显示切换开关并可导出为 CSV - **按主机风险评分** — 0–100 综合得分，基于异常严重性、OT 写入/错误计数、互联网暴露和 TLS 异常；显示在节点详情面板中，并在审计报告中进行排名 - **内联异常解释** — 每个异常徽章都有一个 `ℹ` 按钮；点击它会展开一个“What / Why / Steps”面板，涵盖所有 30 多种异常类型并提供修复指南 - **数据包检查器** — 点击任意边缘或节点打开 Wireshark 风格的面板，包含三个标签：**Packets**（每个数据包的协议树和协议着色的十六进制转储 — 每层以不同的颜色高亮显示）、**Cmd Log**（OT 连接的 OT 命令历史）和 **Stream**（TCP 会话的 ASCII/十六进制 payload 重组）；**⧉ 悬浮按钮** 将检查器分离为可调整大小、可拖动的叠加层；**⊡** 重新停靠它；实时数据包搜索在整个数据包列表（不仅仅是第一页）中显示 `N / M` 计数徽章 - **文件传输检测** — 检测 HTTP 文件下载（Content-Disposition: attachment + 感兴趣的 Content-Type）；侧边栏 “File Transfers” 面板，显示文件名、MIME、大小、SHA-256 哈希、安全的复制/下载控件，以及经过生产测试的提取辅助程序；每次抓包 200 个文件，合并 500 个（按哈希去重） - **PCAP 基线差异对比** — 头部的 “Set Baseline” 按钮；上传第二个 PCAP 并打开 “⊕ Diff” 标签页进行比较：新增/消失的主机（带有具体的更改标签：类型变更、风险差值 >20、新协议、新端口）、带有协议的新连接、流量变化（数据包比率 >2× 或 <0.5×），以及相对于基线的新异常；四列差异对比视图，无需服务器往返 - **异常检测** — 跨通用网络、OT/ICS、IoT 和 VLAN 威胁类别的 32 条检测规则 ### 导出与报告 - **导出** — PNG 图表截图、**Connections CSV**（每个连接及其源/目的国家）、**Hosts Inventory CSV**（每个 IP 一行，国家格式为 “Name (CC)”）、**Anomalies CSV**（带有源/目的国家）、**Credentials CSV**（带有源/目的国家）、Markdown 审计报告（精选发现、抓包摘要、外部端点的地理分布、风险排名、按严重性划分的异常、OT 清单、VLAN 设备清单、按 VLAN 划分的 VLAN 流量、TLS/SNI 观察结果、捕获的凭证、文件传输、OT 写入日志）、**VLAN Inventory CSV**（带有国家）、**VLAN Traffic CSV**（带有源/目的国家）、VLAN Diagram SVG；所有 CSV 导出始终包含完整的数据集，即使图表仅渲染了前 N 个子集 - **会话保存 / 加载** — 将完整的分析、发现和分析师分诊编辑导出为 JSON，并在无需重新上传抓包文件的情况下重新加载；旧的或不完整的会话 JSON 在加载时会进行规范化，因此缺失的可选字段不会破坏 UI ### 用户体验与生产力 - **过滤** — 通过侧边栏复选框按协议或主机类型过滤图表；选择保存到 localStorage，并在下次加载时恢复 - **搜索** — 按 IP 地址或主机名查找节点（300ms 防抖）；`/` 键盘快捷键可聚焦搜索框 - **浅色/深色模式** — 头部的 ☀/☾ 切换开关；为两个主题全面覆盖 CSS 变量；持久化于 localStorage 并防止 FOUC - **可折叠侧边栏** — `‹`/`›` 切换按钮将侧边栏折叠为 32 像素的图标栏；状态持久化于 localStorage - **数据包检查器搜索** — 数据包表上方的实时过滤输入框；匹配任意列文本；显示 `N / M` 计数徽章；切换连接时清空 - **过滤预设** — 将当前的协议 + 主机类型过滤选择保存为命名预设；侧边栏中的芯片列表支持一键加载和删除；跨会话存储在 localStorage 中 - **键盘快捷键** — 按 `?` 打开叠加层：`1`–`9` 切换视图，`F` 适应图表，`/` 聚焦搜索，`空格`/`←`/`→` 控制时间轴刷子，`P` 固定选中节点，`Esc` 关闭面板 - **节点注释** — 右键点击任意节点，使用应用内的备注弹窗附加持久备注（存储在浏览器 localStorage 中） ### 性能 - **大型抓包支持** — 流式处理多达 1,000,000 个数据包而无需全部加载到内存中（每次上传最多 100 个文件 · 总计 1 GB）；多文件上传并行处理 - **性能优化的解析** — C 级别的 MAC/IPv4 格式化（`bytes.hex`、`socket.inet_ntoa`）、分支比较 `conn_key`、提升的广播标志、模块级编译的正则表达式，以及通过每 IP 连接索引实现的 O(C) 风险评分（取代了之前 O(H×C) 的双重扫描）；前端 canvas tick 使用缓存的可见节点集和预计算的每边缘颜色/宽度，小地图限制为每 5 个 tick 执行一次，`applyFilters` 折叠为单次 DOM 遍历 ## 异常检测 32 条检测规则在分析后自动触发： **通用网络** - 端口扫描 — 单一源在 >15 个唯一端口上联系 >5 个 IP - 明文凭证 — 带有 payload 的 FTP 或 Telnet 流量 - **密码重用** — 在 2 个或以上协议或目的主机上观察到相同的密码 - 信标 — 具有高度规律性的包间时间（变异系数 < 0.2）的连接 - 数据渗出 — 主机向非私有 IP 发送超过 10 MB 数据 - 可疑端口 — 已知的 C2/黑客工具端口（4444、1337、31337、6666、6667） - **已知恶意 TLS 指纹** — JA3 哈希匹配精选的恶意软件/C2 工具签名列表（Cobalt Strike、Metasploit、AsyncRAT 等） **OT / ICS** - Modbus 写入命令 (FC 5/6/15/16) — 未经授权的 PLC 写入 - **Modbus 批量寄存器读取** (FC 3/4，数量 >100) — 大规模扫描表明存在侦察 - **Modbus 广播** (unit_id=0) — 命令针对网段上的每个 PLC - **Modbus 异常响应** — 非法功能/地址错误表明存在错误的命令或失败的访问尝试 - DNP3 控制/操作命令（直接操作、Select-Before-Operate、冷/暖重启） - **DNP3 不寻常的功能码** (FC 4 Immediate Freeze Without Reply，FC 14 Warm Restart) — 规避/持久化模式 - S7comm 写入变量和 PLC 停止 / PI 服务命令 - **S7 代码下载** (Request Download FC) — PLC 逻辑正在被修改；提取块类型和编号 - EtherNet/IP CIP Write Tag / Set Attribute 操作 - IEC 60870-5-104 命令激活（Type IDs 45–50，COT=Activation） - BACnet writeProperty / reinitializeDevice / deviceCommunicationControl - OT 设备与互联网主机通信 - 明文 OT 协议（Modbus、DNP3、S7、BACnet 无加密） - **多单元 Modbus 轮询**（来自一个主机的 ≥5 个不同的单元 ID）— PLC 网段的网络映射 **IoT** - 明文 MQTT（端口 1883）— 凭证和传感器数据未加密 - 对 IoT 设备的 Telnet 访问 — 经典的 Mirai 僵尸网络攻击媒介 - IP 摄像头向外部 IP 发送数据 — 未经授权的流或 C2 - TR-069（端口 7547）— 经常被利用的远程管理协议 **VLAN** - 在多个 VLAN 上发现的主机 — 标有 2 个或以上 VLAN ID 的非路由主机；可能存在 VLAN 跳跃攻击 - 未标记 + 已标记帧混合 — 同一主机同时发送未标记和已标记的帧；可能存在原生 VLAN 泄漏 - QinQ（双标签）帧 — 检测到 802.1ad 外部标签；在运营商网络中合法，但是经典的 VLAN 跳跃媒介 - 跨 VLAN OT 流量 — OT/ICS 设备与不同 VLAN 上的主机进行通信；分段违规 - **VLAN 内的 ARP 欺骗** — 同一 IP 在同一 VLAN 上被看到具有 2 个或以上不同的 MAC；可能存在 ARP 中毒或 MAC 抖动 - **广播风暴** — 广播流量 >10%（且 >50 个广播包）的 VLAN；配置错误或环路。将 ARP 帧和 L2 广播（`ff:ff:ff:ff:ff:ff`）目的 MAC 帧与 IP 层广播一起计入每个 VLAN 的总/广播统计中，因为 ARP 在大多数现实世界的风暴中占主导地位；带有明确的 `vlan_id`，因此即使没有源/目的主机，它仍然会落在 VLAN 矩阵的对角线上 - **PCP 优先级滥用** — 终端主机（Windows PC、IP 摄像头、IoT 传感器）发送标记有 PCP ≥ 6（网络控制优先级）的帧；意外的 QoS 操纵 所有异常均显示在侧边栏和节点详情面板中；受影响的节点会闪烁彩色圆环（红色 = 高，黄色 = 中）。 ## OT/ICS 协议支持 该可视化工具可检测并分类工业控制系统设备和协议： **支持的协议：** Modbus TCP、EtherNet/IP、Siemens S7comm、DNP3、IEC 60870-5-104、BACnet、OPC-UA、MQTT、PROFINET、HART-IP、GE SRTP、OMRON FINS、Emerson DeltaV **OT 设备类型：** PLC、RTU、IED、HMI、SCADA Server、DCS、Historian、Engineering Workstation、Building Controller、IoT Gateway、Field Device **OT 厂商指纹识别：** Rockwell Automation、Siemens、Schneider Electric、ABB、Emerson、GE Digital、Honeywell、Yokogawa、WAGO、Phoenix Contact、Mitsubishi Electric、Omron、Beckhoff、Moxa **OT 特定的异常检测：** - Modbus 写入命令 (FC 5/6/15/16) — 未经授权的 PLC 写入 - DNP3 控制/操作命令（直接操作、Select-Before-Operate、冷/暖重启） - S7comm 写入变量、PLC 停止和 PI 服务（启动/停止）命令 - EtherNet/IP CIP Write Tag / Set Attribute 操作 - IEC 60870-5-104 命令激活（Type IDs 45–50，COT=Activation） - BACnet writeProperty / reinitializeDevice / deviceCommunicationControl - OT 设备暴露于互联网流量 - 明文 OT 协议（Modbus、DNP3、S7、BACnet 无加密） **OT 拓扑：** - **OT Map 视图** — 完整的 Purdue 参考模型泳道布局（L0 Field → L6 Public Internet），包含： - 区域分组括号：**Public Internet**（L6，非私有 IP）、**IT Zone**（L4–L5）、**Industrial DMZ**（L3.5）、**OT Zone**（L0–L3） - **Public Internet 区域** — 所有非 RFC1918 IP 地址自动放置于此，无需 GeoIP 数据库；当仅存在私有 IP 时，该区域会被隐藏 - L3.5 和 L4 之间的 IT/OT 分界线 - 描述每个 Purdue 层级代表的内容的级别副标题 - 每个泳道的设备计数 - 用于无法映射到已知 Purdue 层级的设备的 **未分类泳道** - **桥接节点检测**： OT↔IT/Internet 区域的设备以橙色脉冲环高亮显示 - 跨区域边缘高亮（橙色虚线）；OT→Internet 边缘被标记为关键的跨区域行为 - 悬停提示显示 IP、类型、Purdue 层级、协议和连接计数 - `/upload` JSON 响应中每个节点上的 `purdue_level` 字段 - **可编辑模式**（✎ Edit 按钮）— 在 Purdue 泳道之间拖动节点以重新分类，手动添加/移除设备，使用 Critical/High/Medium/Low/Info 风险标签（颜色环 + 徽章）注释节点，然后将带注释的地图导出为 **PNG** 或结构化的 **JSON** - **Purdue 层级徽章** — 显示在每个设备的节点详情面板中 - **跨区域边缘高亮** — 图表视图中跨越 Purdue 层级的连接显示为橙色虚线边缘 - **Engineering Workstation 自动检测** — 发起 S7 Download 会话的主机会自动从未知重新分类为 Engineering Workstation **OT 分析（按节点详情面板）：** - 角色徽章 — 根据 DNP3 方向位和 Modbus 流量模式推导出的主站 / 子站 / 未知 - 读/写/错误比例条 — 跨所有连接边缘的 OT 操作计数汇总 - 轮询的 Modbus 单元 ID — 显示主机查询的 PLC 从站 - 观察到的 DNP3 链路层地址 **协议深度检查（数据包详情面板 + Command Log 标签页）：** - **Modbus TCP**：功能码、单元 ID、寄存器/线圈地址、数量、异常代码和名称；写入命令以红色标出 - **DNP3**：链路层源/目的地址、应用功能码、明确的主站/子站角色、数据对象组（12 个组：Binary Output Control、Analog Input、Class Objects 等） - **S7comm**：ROSCTR 消息类型、PDU 参考、功能码；在下载操作时提取块类型（OB/DB/FC/FB/SFB/SFC）和块编号 - **EtherNet/IP**：封装命令、会话句柄、CIP 服务代码和名称 - **IEC 60870-5-104**：帧类型（I/S/U）、ASDU 类型 ID、传输原因（COT）、公共地址 - **BACnet/IP**：BVLC 功能、APDU PDU 类型、确认/未确认服务名称 **OT Command Log** — 数据包检查器中的专用标签页（仅在 OT 连接上可见），显示紧凑的按时间顺序排列的表格：时间、协议、方向箭头、功能名称、地址/块详情以及 OK/ERR 结果 ## IoT 设备支持 **支持的协议：** MQTT、MQTT-TLS、CoAP、CoAP-DTLS、AMQP、AMQPS、XMPP、RTSP、Matter、WS-Discovery、TR-069、Tuya-IoT、Hikvision、Dahua、DLMS（智能电表） **IoT 设备类型：** IP 摄像头、智能家居网关、智能电表、IoT 传感器、智能音箱、IoT 网关、CPE 设备 **IoT 厂商指纹识别（MAC OUI）：** Amazon Echo、Google Home/Nest、Philips Hue、Samsung SmartThings、Ring、Wyze、TP-Link Kasa、Tuya Smart、Shelly、Particle、Fitbit、LIFX、August Smart Lock **IoT 特定的异常检测：** - 明文 MQTT（端口 1883）— 凭证和传感器数据未加密 - 对 IoT 设备的 Telnet 访问 — 经典的 Mirai 僵尸网络攻击媒介 - IP 摄像头向外部 IP 发送数据 — 未经授权的流或 C2 - TR-069（端口 7547）— 经常被利用的远程管理协议 **协议深度检查：** - **MQTT**：解码消息类型（CONNECT/PUBLISH/SUBSCRIBE）、客户端 ID、主题名称、payload 预览、QoS 级别、凭证存在情况 - **CoAP**：解码消息类型（CON/NON/ACK）、方法/响应代码、URI 路径、payload 预览 ## 环境要求 - Python 3.8+ - pip ## 安装说明 ### 1. 克隆仓库 ``` git clone https://github.com/esandeepchoudary/pcap-vis-anz.git cd pcap-vis-anz ``` ### 2.（可选）创建虚拟环境 ``` python3 -m venv venv source venv/bin/activate # Linux / macOS venv\Scripts\activate # Windows ``` ### 3. 安装依赖 ``` pip install -r requirements.txt ``` ## 使用说明 ``` python app.py # localhost only (default, safe) python app.py --public # expose to your local network — see warning below python app.py --port 8080 # use a different port ``` 然后打开浏览器并访问 `http://localhost:5000`（如果使用了 `--public`，则访问你机器的局域网 IP）。 上传一个抓包文件（`.pcap`、`.pcapng` 或 `.cap`，最大 1 GB），图表将自动渲染。 ## 捕获你自己的流量 如果你手头没有抓包文件，可以使用 `tcpdump` 或 Wireshark 创建一个： ``` # 在任意 interface 上捕获 60 秒的流量 sudo tcpdump -i any -w capture.pcap -G 60 -W 1 # 或者在特定的 interface 上捕获 sudo tcpdump -i eth0 -w capture.pcap ``` 示例 `.pcap` 文件也可在 [https://www.malware-traffic-analysis.net](https://www.malware-traffic-analysis.net) 和 [Wireshark 示例抓包页面](https://wiki.wireshark.org/SampleCaptures) 获取。 ## 项目结构 ``` pcap-vis-anz/ ├── app.py # Flask backend + PCAP parser (scapy) ├── requirements.txt # Python dependencies ├── LICENSE # MIT ├── docs/ # Generated tutorial + product docs (Markdown) ├── site/ # Docusaurus site serving docs/ — see site/README.md ├── tours/ # Tour specs driving the docs generation ├── fixtures/ # Demo capture used to generate doc screenshots ├── data/ │ ├── dbip-country-lite.mmdb # Bundled DB-IP Country Lite GeoIP DB (CC BY 4.0) │ └── DB-IP-LICENSE.txt # Attribution and refresh instructions ├── templates/ │ └── index.html # Single-page app shell ├── static/ │ ├── css/style.css # Dark GitHub-style theme │ └── js/app.js # D3.js force graph + UI logic └── tests/ ├── conftest.py # Shared pytest fixtures and packet builders ├── test_parsers.py # Protocol parser unit tests (Modbus, DNP3, S7, CoAP, …) ├── test_anomalies.py # Anomaly detection rule tests ├── test_anomalies_ot.py # OT/IoT anomaly rule tests (Modbus writes, DNP3 control, S7, EtherNet/IP, IEC-104, BACnet, IoT) ├── test_credentials.py # Credential extraction tests ├── test_file_cache.py # Captured file download-cache tests ├── test_file_extraction.py # HTTP file transfer detection tests ├── test_frontend_findings_static.py # Static frontend regression tests ├── test_geoip.py # GeoIP bundled-DB and geo_lookup() tests ├── test_helpers.py # Helper function tests (is_private, mac_vendor, geo_lookup) ├── test_http_mqtt_coap.py # HTTP / MQTT / CoAP parser tests ├── test_ipv6_ext_headers.py # IPv6 extension-header parsing tests ├── test_merge.py # Multi-file merge tests ├── test_pcapng.py # pcapng parse and parity tests ├── test_routes.py # /upload endpoint HTTP tests (happy path, errors, file count cap) ├── test_serialization.py # Output schema and truncation-flag tests ├── test_vlan.py # VLAN parsing, merge, stats, and anomaly tests └── test_utils.py # Utility function tests ``` ## 测试 ``` pip install pytest # or: pip install -r requirements-dev.txt pytest tests/ -q ``` 该测试套件包含 18 个文件中的 354 个测试，涵盖协议解析器、异常检测（包括所有 16 条 OT/IoT 规则）、凭证提取、文件传输检测、多文件合并、全保真度序列化（无端口/DNS 截断）、GeoIP 打包、前端回归防护以及 `/upload` HTTP 端点。 ## 配置 | 设置 | 默认值 | 描述 | |---|---|---| | `MAX_UPLOAD_FILES` | 100 | 每次上传请求的最大文件数 | | `MAX_CONTENT_LENGTH` | 1 GB | 最大总上传大小 | | `MAX_PACKETS` | 1,000,000 | 每个文件处理的数据包数 | | `MAX_HOSTS` | 250,000 | 兜底限制 — 每个文件的最大唯一主机数（解析时的安全防护；很少触发） | | `MAX_CONNECTIONS` | 1,000,000 | 兜底限制 — 每个文件的最大唯一 IP 对数（解析时的安全防护；很少触发） | | `MAX_STORED_PER_CONN` | 50 | 为检查器存储的每个连接的数据包数 | | `_FILE_CACHE_MAX_BYTES` | 256 MB | 用于捕获文件正文的内存预算 | | `RENDER_NODE_CAP` | 1,500 | 力导向图中绘制的最大 SVG 节点组数（见下文） | | `RENDER_EDGE_CAP` | 4,000 | 力导向图中绘制的最大边缘数（SVG/canvas） | | `MAX_CRED_STATE_ENTRIES` | 5,000 | 每个协议（Telnet、FTP 等）的半开凭证状态条目；在模块级别设置，因此可以在测试中覆盖 | | 检查器中的连接 | 前 40 个 | 具有数据包详情的连接（按数据包计数） | | 每个节点显示的端口 | 30 | 详情面板中列出的开放端口 | | 每个节点的 DNS 名称 | 5 | 详情面板中显示的已解析主机名 | | 每个节点的 DNS 查询 | 10 | 详情面板中显示的 DNS 查询 | | 端口 | 5000 | HTTP 端口（`--port` 标志） | ### 全保真度导出与渲染上限对比 后端会解析并序列化**所有**直到兜底限制的主机和连接。CSV 导出（Connections、Hosts Inventory、VLAN Inventory、VLAN Traffic）始终使用完整的数据集 — 不会因为 UI 渲染决定而从导出中省略任何连接或 IP。 当抓包包含超过 `RENDER_NODE_CAP` 的主机时，图表视图仅渲染流量最大的前 N 个主机，并显示一个蓝色横幅：*"Graph shows top N of M hosts — exports contain the full dataset."* **Table 视图**和所有 CSV 导出仍然反映每个主机和连接。仅当实际超出了解析时的兜底限制（25 万个主机 / 100 万个连接）时，`/upload` JSON 响应中的 `stats.hosts_truncated` / `stats.connections_truncated` 标志才为 `true`。 ## 安全性与自包含 此工具专为**隔离网 / 离线使用**而设计： - D3.js v7 在本地打包 — 无 CDN 请求 - **打包 GeoIP 数据库** — [DB-IP Country Lite](https://db-ip.com) (CC BY 4.0) 内置为 `data/dbip-country-lite.mmdb`；无需互联网连接或 MaxMind 帐户。国家名称、ISO 代码和国旗 emoji 开箱即用。归属：*IP Geolocation by DB-IP*。 - CSS 仅使用系统字体 — 无 Google Fonts - 浏览器唯一的出站请求是发往同源的 `POST /upload` - PNG 导出使用 `blob:` URL — 无第三方图片托管 **使用更丰富的 GeoIP 数据库：** 内置的 DB-IP Country Lite 仅解析国家（没有城市名称）。如果你有城市级别的数据库（`GeoLite2-City.mmdb` 或 `dbip-city-lite.mmdb`），你可以将应用指向它： ``` # Environment variable（适用于 python app.py 和 gunicorn） GEOIP_DB_PATH=/path/to/GeoLite2-City.mmdb python app.py # 或者将其放置在默认的系统路径（会在内置 DB 之前检查） /usr/share/GeoIP/GeoLite2-City.mmdb ``` **刷新内置数据库：** DB-IP 每月发布免费更新。 ``` YYYYMM=2026-07 # update to the target month curl -L -o /tmp/dbip.mmdb.gz \ "https://download.db-ip.com/free/dbip-country-lite-${YYYYMM}.mmdb.gz" gunzip -c /tmp/dbip.mmdb.gz > data/dbip-country-lite.mmdb ``` 每个响应都会设置 HTTP 安全标头（`Content-Security-Policy`、`X-Content-Type-Options`、`X-Frame-Options`、`Referrer-Policy`）。该应用默认绑定到 `127.0.0.1`，因此无法从网络访问。传递 `--public` 以绑定到 `0.0.0.0` 以进行局域网访问 — 仅在受信任的网络上执行此操作，因为该应用会处理潜在敏感的抓包文件。 v0.9 中应用的健壮性强化：所有 API 端点都返回 JSON 错误（包括 413/404/500），捕获的文件正文有内存限制（256 MB 缓存），连接/主机/DNS/凭证状态表有上限限制，下载文件名使用 `secure_filename` 进行清理，并且会话导入验证器会在非数组形状到达渲染器之前拒绝它们。 ## 故障排除 **`scapy` 导入错误** — 确保你在正确的 Python 环境（或虚拟环境）中安装了依赖项。 **读取 pcap 权限被拒绝** — 某些系统需要 root 权限才能读取某些抓包文件。尝试使用 `sudo python app.py`。 **上传后图表为空** — 文件可能仅包含非 IP 流量（例如纯蓝牙或 USB 抓包）。该工具支持 IPv4、IPv6 和 ARP 数据包。 **超大文件速度缓慢** — 仅处理前 1,000,000 个数据包。要获得更快的结果，请使用 `tcpdump` 进行预过滤： ``` tcpdump -r big.pcap -w filtered.pcap 'tcp or udp' ``` ## 许可证 [MIT](./LICENSE) — Copyright (c) 2026 Sandeep Egalapati

标签：PB级数据处理, PCAP分析, 安全运维, 异常检测, 数据可视化, 网络流量分析, 调试辅助, 逆向工具, 防御绕过