Star15
0
代码
代码
Issues
Pull Requests
项目讨论
Wiki
分析
Star15
0
XXHeartdocs: README 补充安装与调试说明，移除所有 emoji
86ce2059创建于 8月9日历史提交

OhShark — Wireshark 鸿蒙版

OhShark 将 Wireshark 移植到 HarmonyOS / OpenHarmony (OHOS) 平台，可在鸿蒙平板/2in1 设备上运行完整的 Wireshark Qt GUI，并通过 VPN/TUN 方案实现本地抓包。

基于 Wireshark 4.0.9（wireshark-qt5 分支源码）与 Qt 5.12.12 for OHOS，使用 OHOS NDK Clang 交叉编译。

构建状态

组件 状态
libwireshark.so.16（核心解析引擎） 编译成功
libwireshark_qt.so（Qt GUI） 编译成功，窗口正常渲染
接口列表 启动后自动刷新（约 100ms），无需手动 Refresh
启动弹窗 已抑制，错误改为日志输出（不再弹出 "Multiple problems found"）
VPN/TUN 抓包 可用：点击接口开始抓包，流量经 TUN → pcap → Qt 界面显示
原始 AF_PACKET 抓包 沙箱 SELinux 禁止（EACCES），改用 VPN/TUN 方案

环境要求

构建主机

  • Windows (x86_64)
  • CMake >= 3.13 + Ninja
  • Python 3（运行二进制补丁脚本）
  • DevEco Studio（含 OHOS NDK / HarmonyOS SDK，用于 HAP 打包与签名）
  • Qt 5.12.12 for OHOS (arm64-v8a，预编译于 ohos_deps/ohos/qt5)

关键依赖路径

组件 路径
OHOS NDK F:\AppInstallation\Huawei\DevEco Studio\sdk\default\openharmony\native
Qt 5.12.12 for OHOS ohos_deps/ohos/qt5
glib / libintl (arm64) ohos_deps/ohos/glib-arm
libpcap (arm64) ohos_deps/ohos/libpcap

仓库结构

OH-Shark/
├── wireshark-qt5/                # Wireshark 4.0.9 源码 + OHOS 移植（构建源码）
│   ├── ohos/                     # OHOS 适配：stubs、qpa、capture 的 VPN 抓包分支
│   ├── build_ohos2/              # 交叉编译输出（run/ 下为 .so 产物）
│   ├── ui/qt/                    # Qt GUI 源码（已含 OHOS 修改）
│   └── dumpcap.c / capture/      # 抓包：VPN/TUN pcap 文件读取（ohos_growing_file）
├── ohos_deps/                    # 预编译依赖（Qt5/glib/libpcap/libintl，Git LFS）
├── ohos/wireshark_app_qt/        # DevEco Studio HAP 工程
│   ├── entry/                    # 主模块：QAbility + QEmbeddedUiExtensionAbility + SharkVpnAbility
│   │   ├── src/main/ets/         # ArkTS：Qt 嵌入、VPN trigger 轮询器
│   │   ├── src/main/cpp/         # native：tun_capture.c（TUN → pcap）
│   │   └── libs/arm64-v8a/       # 部署的交叉编译 .so（含二进制补丁）
│   ├── qEmbeddedUiExtensionHost/ # 嵌入式 UI 扩展模块（EmbedQtAbility）
│   └── scripts/
│       └── patch_qt_libs.py      # 运行时必需二进制补丁
├── DEPENDENCIES.md               # 依赖与完整复现步骤
├── DEVELOPMENT_LOG.md            # 开发日志
└── 开发日志.md                    # 会话级开发日志

快速构建

完整可复现流程见 DEPENDENCIES.md。要点：

# 1. 交叉编译 Wireshark 库（在 wireshark-qt5 目录，构建树 build_ohos2）
cmake -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=<abs>/wireshark-qt5/cmake/cross-compile/ohos-aarch64.cmake \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DBUILD_wireshark=ON -DBUILD_dumpcap=ON -DBUILD_tshark=ON -DBUILD_logray=OFF \
  <abs>/wireshark-qt5
ninja -C build_ohos2 wireshark_qt

# 2. 同步库到 HAP 工程（版本化命名）
#    build_ohos2/run/libwireshark_qt.so → ohos/wireshark_app_qt/entry/libs/arm64-v8a/
#    libwsutil.so.14 / libwiretap.so.13 / libwireshark.so.16

# 3. 应用运行时必需二进制补丁
python ohos/wireshark_app_qt/scripts/patch_qt_libs.py ohos/wireshark_app_qt/entry/libs/arm64-v8a

# 4. DevEco Studio 打开 ohos/wireshark_app_qt → 配置签名 → 构建

注意：patch_qt_libs.py 的补丁偏移每次重链后都会漂移，必须用 llvm-objdump 重新定位 ws_init_version_info 与 wg_mix_hash 调用点后再运行。

安装与调试

生成 HAP 包

在 DevEco Studio 中打开 ohos/wireshark_app_qt，配置签名后构建（Build → Build HAP(s) 或 hvigorw assembleHap）。会产出两个模块的 HAP：

ohos/wireshark_app_qt/entry/build/default/outputs/default/entry-default-signed.hap
ohos/wireshark_app_qt/qEmbeddedUiExtensionHost/build/default/outputs/default/qEmbeddedUiExtensionHost-default-signed.hap

签名（必需）

  • 包名：com.soulharbor.ohshark
  • DevEco Studio 中：File → Project Structure → Signing Configs → 勾选 Automatically generate signature（需登录华为账号）。
  • 签名与包名必须匹配：若修改了 AppScope/app.json5 的 bundleName，必须在 DevEco 中重新自动签名，否则构建报 00303074 Configuration Error。

安装两个 HAP（缺一不可）

本项目由 entry 与 qEmbeddedUiExtensionHost 两个模块组成：

  • entry：主 Ability（QAbility 桌面入口）、Qt 窗口宿主扩展（QEmbeddedUiExtensionAbility）、VPN 抓包扩展（SharkVpnAbility）。
  • qEmbeddedUiExtensionHost：嵌入式 UI 扩展（EmbedQtAbility）。

只安装其中一个会导致问题：Qt 窗口渲染所需的 QEmbeddedUiExtensionAbility 在 entry 中，若未安装 entry，界面白屏、无法启动 Qt 窗口。两个 HAP 都必须安装。

用 hdc 安装：

hdc tconn <设备IP>:<端口>          # 连接设备（若用 USB 可跳过）
hdc install ohos/wireshark_app_qt/entry/build/default/outputs/default/entry-default-signed.hap
hdc install ohos/wireshark_app_qt/qEmbeddedUiExtensionHost/build/default/outputs/default/qEmbeddedUiExtensionHost-default-signed.hap

或在 DevEco Studio 中直接 Run（会自动部署所有模块）。

启动与验证

# 启动（桌面入口 QAbility；或指定 Embedded 入口）
hdc shell aa start -a QAbility -b com.soulharbor.ohshark

# 确认进程（主进程 + VPN 扩展进程应出现）
hdc shell ps -ef | grep soulharbor

# 抓包验证：应用界面点击接口开始抓包，浏览器访问网站，界面应实时显示数据包
# VPN 扩展进程（com.soulharbor.ohshark:vpn）应在运行

调试手段

  • 接口列表未显示：正常情况下启动约 100ms 后自动刷新。若为空，检查 entry HAP 是否安装（缺少 QEmbeddedUiExtensionAbility 会导致 Qt 窗口/抓包异常）。
  • 抓不到包：确认 VPN 扩展进程 com.soulharbor.ohshark:vpn 是否运行。抓包链路：capture_start 写 trigger → VpnTriggerPoller（QAbilityStage / QEmbeddedUiExtensionAbility 启动）→ SharkVpnAbility 建 TUN → tun_capture.c 写 pcap → dumpcap 读取。
  • 运行时日志：
    • hdc hilog 抓系统日志，过滤 OHOSHARK（native 诊断）、VpnPoller（VPN 轮询器）、OHDIAG（扩展诊断）。
    • hdc shell find /data/log/faultlog -name '*soulharbor*' 查崩溃记录。
  • 重装：安装新 HAP 前建议先停应用 hdc shell aa force-stop com.soulharbor.ohshark。卸载旧包后再装新包（hdc uninstall com.soulharbor.ohshark）。

抓包方案（VPN/TUN）

鸿蒙沙箱禁止原始套接字抓包（AF_PACKET EACCES），因此采用 VPN/TUN 方案：

  1. Qt 侧 capture_start() 写入 trigger 文件 ohshark_vpn_trigger
  2. VPN trigger 轮询器（VpnTriggerPoller.ets，由 QAbilityStage 与 QEmbeddedUiExtensionAbility 共享启动）读到 trigger → 调起 SharkVpnAbility
  3. SharkVpnAbility（VpnExtensionAbility）创建 TUN 连接，把 fd 交给 native tun_capture.c 写入 pcap 文件
  4. dumpcap 以 growing-file 模式读取该 pcap 文件 → Qt GUI 实时显示

流量策略：trustedApplications: []（所有应用走 VPN）+ blockedApplications: ['hishell']（仅屏蔽系统桌面），实现全设备应用流量抓取。

技术要点

  • Qt 版本：Wireshark 4.0.9 原生 Qt5 源码（wireshark-qt5 分支），配合 Qt 5.12.12 for OHOS
  • 交叉编译：OHOS NDK Clang（aarch64-linux-ohos）+ 自定义 toolchain
  • OHOS Qt QPA：Qt 5.12.12 libqohos.so，通过 XComponent 桥接 ArkUI 渲染
  • 入口机制：QAbility（桌面入口）与 EmbedQtAbility（嵌入式入口）两条路径；VPN 轮询器在两条路径下均可用
  • 二进制补丁（运行时必需）：
    • libwireshark_qt.so：跳过 ws_init_version_info（OHOS 上 garbage %s 崩溃）
    • libwireshark.so.16：跳过 WireGuard wg_mix_hash（gcrypt 无 BLAKE2S）
  • 启动体验优化：
    • 接口列表启动 100ms 后自动刷新（弥补沙箱内 iface_mon 不可用）
    • 启动期 report 弹窗抑制为日志输出

许可

Wireshark 基于 GPLv2 许可。详见 COPYING。

原版信息

官方 Wireshark 主页：https://www.wireshark.org