CodeQL 鸿蒙 PC 适配全记录：让 ArkTS 项目拥有可落地的安全分析闭环

忆凡_

16人浏览 · 2026-09-13 16:07:16

忆凡_ · 2026-09-13 16:07:16 发布

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_codeql

一、为什么要适配 CodeQL

HarmonyOS PC 的应用形态正在从系统工具和基础办公软件，逐步扩展到开发、测试和安全工程。应用数量增加之后，工程质量不能只依赖编译器报错与人工审查：网络明文传输、WebView 危险选项、Ability 暴露、敏感信息硬编码、日志泄露以及不可信参数流向文件或网络等问题，都需要能够在提交前稳定复现、批量检查并留下机器可读结果。

CodeQL 的价值恰好在于把源码视为可查询数据库。规则作者可以围绕语法、配置、调用关系和数据流编写查询，项目团队则可以把同一组查询用于本地检查、持续集成和审计复核。但 CodeQL 上游主要面向已经成熟的语言与桌面工作流，无法直接理解 ArkTS 装饰器、ArkUI 声明式组件以及 HarmonyOS 的 module.json5、app.json5 等工程描述文件，也没有一个可以直接安装到鸿蒙 PC 的独立应用入口。

本次适配因此同时处理两条链路：一条是分析能力，为 ArkTS 与 HarmonyOS JSON5 配置补充识别、建模和安全查询；另一条是用户入口，以原生 ArkUI 重建独立 CodeQL 工作区，让“导入项目—创建数据库—选择查询—运行分析—定位源码—导出结果”可以在鸿蒙 PC 窗口中连续完成。

当前应用版本为 0.1.0，包名为 com.github.codeql.harmony，目标 SDK 与兼容 SDK 均为 6.0.2(22)，支持 2in1 和 tablet。需要先说明的是：HAP、窗口和交互已经原生运行在鸿蒙 PC 上；CodeQL CLI 与查询求值器当前仍由主机侧服务承载，应用通过 HTTP 调用。它是一套已经跑通的服务型独立应用，但还不是把完整分析引擎塞进 HAP 的离线版本。

二、先确定适配边界：不是给命令行套一层界面

CodeQL 仓库包含多语言提取器、标准库、查询、测试与构建配置。真正执行建库和查询的 CLI 又有独立的发行与运行时要求。若只做一个可以显示规则名称的界面，ArkTS 仍然无法进入数据库；若只增加若干 QL 文件，普通用户又必须回到命令行拼装数据库路径、搜索路径和 BQRS 解码参数。

本项目按职责把能力拆为三层：

层次	主要职责	当前实现
HarmonyOS PC 应用	项目、数据库、查询、历史、结果与导出交互	Stage 模型 + ArkUI 独立 HAP
分析服务	管理项目快照、后台任务、CLI 进程和结果格式	Node.js HTTP 服务，无编辑器 API 依赖
CodeQL 适配包	识别 ArkTS/JSON5，提供模型与安全查询	`codeql/harmony-all` 与 `codeql/harmony-queries`

这样的边界保留了 CodeQL 原有分析语义，同时避免让 HAP 直接管理体积较大、依赖复杂的 CLI 进程。开发阶段可通过 HDC 反向端口连接本机服务；后续若具备设备内可用的 CLI/HNP 运行时，也可以保持 HTTP 契约不变，只替换服务部署位置。

三、鸿蒙版本的整体架构

独立应用位于 harmony/app/。EntryAbility 负责 Stage 生命周期并加载 pages/Index，ArkUI 页面维护服务状态、项目状态、数据库、查询目录、后台 Job、历史记录和分析结果。它不加载其他代码编辑器的 Web 工作台，也不依赖外部编辑器扩展宿主。

HarmonyOS PC HAP
    ├── EntryAbility / ArkUI 独立窗口
    ├── 项目与 ZIP 导入、数据库和查询选择
    ├── 后台任务状态、结果列表与源码预览
    └── CSV / SARIF 导出
             │ HTTP
             ▼
standalone-codeql-service.mjs
    ├── 项目快照与安全路径校验
    ├── ArkTS / JSON5 分析镜像
    ├── codeql database create
    ├── codeql query run
    ├── BQRS 解码、历史与任务取消
    └── 源文件上下文读取
             │
             ▼
codeql/harmony-all + codeql/harmony-queries
    ├── HarmonyOS 文件、模块、Ability 与权限模型
    ├── ArkUI、路由、网络、存储、IPC 与 WebView 模型
    └── 29 条清单查询和安全规则

分析层对 .ets 文件生成尽量保持字符位置的 TypeScript 分析镜像，使现有 JavaScript/TypeScript 提取器可以接住 ArkTS 源码；对 HarmonyOS JSON5 配置则生成可分析的结构化镜像。查询结果再映射回项目原始相对路径与行列位置，设备端点击告警时读取的仍是原始 .ets 文件，而不是中间产物。

四、把核心分析流程在真机上跑通

以下五张截图均取自仓库当前签名 HAP 在鸿蒙 PC 真机上的实际运行画面。验证设备为 HUAWEI MateBook Pro（HAD-W32，arm64-v8a），系统版本为 HAD-W24 6.1.0.117(SP78C00E100R13P3)，物理分辨率为 3120×2080。测试时重新安装了当前 358 KB 的签名产物，并通过 HDC 反向端口连接 CodeQL CLI 2.26.2 服务。

1. 独立工作区连接真实分析服务

应用启动后，左侧工作区同时呈现数据库、查询目录、项目导入和服务地址；主区域显示数据库数、发现数与查询数。截图中底部状态栏已经读取到 CodeQL CLI 2.26.2，数据库 ArkSecure Notes database 的状态为 ready，查询目录实际加载出 29 条 HarmonyOS 查询。

在这里插入图片描述

服务检查并不是本地写死的版本文本。页面会依次访问 /health、/v1/queries、/v1/databases 和 /v1/history；任一连接失败时界面会回到 Service offline，不会用演示数据掩盖服务状态。数据库、历史和规则目录也都来自当前服务数据目录。

2. 查询库直接解释规则意图

选择 Cleartext URL literal in HarmonyOS source 后，页面进入 Query library，并显示规则说明：明文 HTTP 地址可能使 HarmonyOS 应用流量遭受拦截或篡改。规则目录还包括 WebView 明文加载与危险选项、导出 Ability 权限、硬编码敏感值、敏感日志、弱加密、路由参数流向文件或 WebView 等检查。

在这里插入图片描述

查询目录来自 harmony/ql/src/ 中 QL 文件的元数据，而不是另一份需要人工维护的菜单清单。新增规则并补齐 @name、@description、@kind、@id 等元数据后，服务即可将其纳入目录，减少规则实现与客户端显示不一致的问题。

3. 从 ArkTS 工程生成可查询数据库

真机选择的数据库页显示 ArkSecure Notes database，语言为 javascript，状态为 ready。本次验证项目包含 .ets 与 HarmonyOS JSON5 描述文件；服务先生成分析镜像，再实际调用 codeql database create，完成提取、TRAP 导入、关系合并和源码归档。

在这里插入图片描述

数据库创建通过后台 Job 执行，HAP 不会在长任务期间阻塞主线程。界面按任务 ID 轮询状态，并区分 running、cancelling、completed 和失败状态；服务端保存标准输出、标准错误、退出码以及数据库与项目的关联，便于复核一次建库到底处理了哪些内容。

4. 真正运行查询并返回阳性安全发现

为了验证阳性链路，测试项目在 entry/src/main/ets/pages/Index.ets 中放入一个非本机的 http:// 服务地址。真机点击运行后，CodeQL 完成 QL 编译与求值，结果区返回 1 条 warning，指出命中文件、行列位置和完整风险信息；CSV 与 SARIF 导出按钮也随有效结果启用。

在这里插入图片描述

这条结果来自真实 BQRS 文件的解码。规则排除了 localhost、127.0.0.1 和 0.0.0.0 等本地开发地址，命中的是 http://api.demo.internal/v1/notes。服务还可把同一结果解释为 SARIF 2.1.0，保留规则 ID harmony/cleartext-url-literal，便于后续接入流水线和审计平台。

5. 从告警回到原始 ArkTS 上下文

点击告警后，应用根据项目 ID、原始相对路径和命中行请求源码上下文。截图中第 1 行以 › 标出，底部同时显示 entry/src/main/ets/pages/Index.ets:1:26 和规则 ID，完成了从数据库结果回到原始 ArkTS 文件的定位。

在这里插入图片描述

源码预览接口会拒绝 .. 等越界路径，并把请求限制在已登记的项目根目录内。这里尤其不能直接展示分析镜像：预处理后的文件可以服务于提取，但读者修复的对象始终应当是项目中的原始 .ets 文件。位置保持与路径回映是否准确，决定了这套工具能否从“发现问题”继续走到“修改问题”。

五、适配过程中最棘手的几个问题

难点一：ArkTS 不是改个扩展名就能当 TypeScript

ArkTS 包含 @Entry、@Component、状态装饰器、声明式 UI 构建语法和平台导入。直接把 .ets 交给通用 TypeScript 提取器，会在装饰器或 UI DSL 处出现语法诊断；如果粗暴删除不支持的代码，后续行列位置又会整体偏移。

适配层采用“分析镜像”而不是修改用户源码：识别 ArkTS 结构，对提取器暂不能接受的片段进行长度尽量保持的替换，同时保留字符串、调用和标识符等安全查询需要的内容。这个策略无法一开始覆盖 ArkTS 的全部语义，但能让文件识别、组件清单、平台 API 调用和多类安全规则先形成稳定闭环。

难点二：JSON5 配置也是安全语义的一部分

HarmonyOS 的包名、模块、Ability、导出状态、权限和入口大多位于 JSON5 文件。仅分析 .ets，就无法判断一个 Ability 是否对外暴露、是否声明访问权限，也无法把源码中的 WebView 使用和模块配置联系起来。

项目为 app.json5、module.json5、oh-package*.json5、build-profile.json5 等配置生成分析镜像，并在 harmony.qll 中建立应用、模块、Ability 和权限模型。配置文件名、嵌套字段和源码入口之间必须使用同一套路径规则，否则查询虽然能编译，却会在真实工程上失去结果。

难点三：设备端应用与分析引擎之间要有可信边界

CodeQL CLI 依赖自身发行物、查询包和运行时，当前真机系统没有直接提供 codeql、Java 或 Node.js 命令。把完整引擎已经原生移植到设备上并不符合实际，因此本次选择显式的服务边界：HAP 只通过受控 API 提交项目快照和任务，服务负责启动 CLI。

这条边界也带来安全要求。服务默认只监听 127.0.0.1；若绑定非回环地址，必须启用令牌。项目导入限制文件数量、总体积、单文件大小和允许的相对路径，查询执行只能访问配置好的查询根目录或搜索路径，删除操作也只能处理服务数据目录内的托管资源。

难点四：后台 Job、历史与导出必须指向同一份结果

建库和查询都可能持续较长时间，不能把一次 HTTP 请求一直挂在前台。服务因此为每个任务生成 Job ID，保存状态、日志、退出码和结果 ID；HAP 轮询任务并允许取消。查询完成后，同一个结果 ID 继续用于 BQRS JSON 解码、详情列表、CSV、SARIF、历史重开和源码预览。

若这些环节各自重新推断数据库或查询路径，很容易出现界面显示 A 规则、导出却属于 B 规则的情况。当前状态模型把 databaseId、queryId、resultId、原始项目 ID 和输出文件绑定在一条记录中，历史页重新打开时仍能恢复相同发现。

难点五：HarmonyOS 文件授权与传统桌面路径不同

桌面工具通常假设用户选中目录后即可递归读取任意文件；HarmonyOS 的系统选择器返回 URI，具体设备镜像对目录枚举的支持又可能不同。应用首先尝试目录导入；目录 URI 无法枚举时，可回退到 ZIP 或多文件选择。ZIP 在服务端解包前需要检查绝对路径和 .. 路径，避免压缩包把文件写到项目目录之外。

这也是当前仍需继续完善的部分：服务型闭环已经可用，但设备端通用目录授权、超大型工程上传和断点续传还需要结合后续系统文件接口演进。

六、构建、安装与运行

1. 安装分析侧依赖

开发机需要可执行的 CodeQL CLI 及 Node.js。仓库当前使用 CodeQL CLI 2.26.2 完成验证，QL 包位于 harmony/ql/lib 与 harmony/ql/src。首次使用或锁文件更新后，可在仓库根目录执行相应的 codeql pack install。

2. 启动独立分析服务

node harmony/tools/standalone-codeql-service.mjs \
  --host 127.0.0.1 \
  --port 18766 \
  --data-dir /path/to/codeql-service-data \
  --query-root /path/to/ohos_codeql/harmony/ql/src

启动后可以先检查健康状态和查询目录：

curl http://127.0.0.1:18766/health
curl http://127.0.0.1:18766/v1/queries

3. 构建签名 HAP

使用 DevEco Studio 打开 harmony/app/ 并配置与设备匹配的签名，或在工程目录执行：

cd harmony/app

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
HOS_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleHap --mode module -p product=default --no-daemon

签名产物位于：

harmony/app/entry/build/default/outputs/default/entry-default-signed.hap

4. 真机安装、端口连接与启动

HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

"$HDC" list targets
"$HDC" install -r harmony/app/entry/build/default/outputs/default/entry-default-signed.hap
"$HDC" rport tcp:8765 tcp:18766
"$HDC" shell aa force-stop com.github.codeql.harmony
"$HDC" shell aa start -a EntryAbility -b com.github.codeql.harmony

应用默认访问 http://127.0.0.1:8765。反向端口建立后，设备侧 8765 会映射到开发机 18766。正式部署若改为局域网或远程服务，应使用 HTTPS、认证、访问控制和独立的数据目录，不能照搬开发阶段的无令牌回环配置。

七、当前已经覆盖的能力与明确边界

当前版本已经形成以下可用能力：

原生 ArkUI 独立窗口、CodeQL 图标、深色工作区和可调整 PC 窗口；
服务健康检查、CodeQL CLI 版本读取与离线状态提示；
目录、ZIP 和多文件项目导入回退；
ArkTS 与 HarmonyOS JSON5 分析镜像；
数据库创建、登记、列表、删除、升级和清理接口；
29 条 HarmonyOS 清单查询与安全规则目录；
后台查询、任务取消、结果详情和查询历史；
告警文件、行列位置和原始源码上下文预览；
CSV 与 SARIF 2.1.0 结果导出。

目前仍需明确保留以下边界：

CodeQL CLI/分析引擎尚未内置到 HAP，设备完全离线分析未完成；
ArkTS 适配目前复用 JavaScript/TypeScript 提取器与分析镜像，不等同于覆盖全部 ArkTS 类型系统语义；
大型工程的增量上传、断点续传、结果分页和全量数据流可视化仍待完善；
不同设备镜像对目录 URI 的枚举能力存在差异，必要时使用 ZIP 或多文件回退；
生产环境的远程服务需要补齐 HTTPS、身份认证、配额、审计和多租户隔离。

把这些边界写清楚并不削弱当前成果。现阶段已经验证的是一条真实、可复现的安全分析主链路；尚未具备的设备内 CLI 和完整语言语义，则继续作为下一阶段工程目标，而不是用界面效果代替。

八、真机验证结果

本文截图对应的复测结果如下：

Device: HUAWEI MateBook Pro (HAD-W32)
System: HAD-W24 6.1.0.117(SP78C00E100R13P3)
Target: 3QC0124C20001268
Architecture: arm64-v8a
Bundle: com.github.codeql.harmony
Application: 0.1.0
CodeQL CLI: 2.26.2
HarmonyOS queries: 29
Database: ArkSecure Notes database · ready
Query: harmony/cleartext-url-literal
Result: completed · 1 finding
Location: entry/src/main/ets/pages/Index.ets:1:26
Source preview: passed

复测不是只确认窗口能够打开。签名 HAP 重新安装成功，Stage Ability 正常启动；应用通过 HDC 反向端口读取服务健康信息、数据库与查询目录；真机发起查询后，服务实际生成 BQRS，设备端显示 1 条阳性结果；点击结果又成功读取原始 ArkTS 上下文。五张截图分别保留了这条链路上的关键状态。

九、总结

CodeQL 的鸿蒙 PC 适配并不是简单增加文件扩展名，也不是给命令行包一层窗口。真正决定可用性的，是 ArkTS 与 JSON5 能否稳定进入数据库，规则结果能否保留原始路径和行列，长任务能否取消和追溯，以及用户能否从一条告警继续回到源码并导出标准结果。

本项目以分析镜像接入现有提取器，用 HarmonyOS QL 包补足应用、模块、Ability、权限与平台 API 模型，再用独立 ArkUI HAP 承接项目、数据库、查询、历史和结果交互。真机复测已经跑通服务连接、29 条查询加载、数据库识别、明文 URL 阳性发现和源码定位，说明当前版本已经越过“只能编译或只能展示界面”的阶段。

下一步工作的重点很明确：继续提高 ArkTS 语义精度，完善大工程导入与结果分页，并评估可在鸿蒙设备侧部署的 CodeQL 运行时或受认证分析服务。在这些基础补齐之前，坚持把已经验证的能力与尚未完成的边界分开描述，才能让适配成果真正可维护、可复现，也便于后续规则作者和项目团队继续扩展。