鸿蒙三方库依赖漏洞审计实战:源码级移植 kotlin-semver,把 CVE 门禁做进 KMP 应用
社区引导:欢迎加入 KMP&CMP 鸿蒙社区,一起把鸿蒙的系统能力带给每一个跨端开发者。
KMP/CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP
提交仓库:https://atomgit.com/oh-tpc/kmp-ohos-sec-baseline
参考框架与社区组织:https://atomgit.com/oh-tpc | https://atomgit.com/CPF-KMP-CMP
Kotlin 2.2.21 / Compose Multiplatform 1.9.2 / HarmonyOS SDK 6.0.0(20)
全部代码跑在真机 ohosArm64 上,36 个 JVM 单元测试全绿,工程已开源。
「这个版本有没有 CVE?」——在 JVM 和 Android 世界,这通常交给 Dependency-Check、Trivy 或 GitHub Dependabot 在云端回答。可到了鸿蒙(HarmonyOS NEXT / OpenHarmony)工程,答案并不容易拿到:依赖散落在 libs.versions.toml、oh-package-lock.json5 两种生态;鸿蒙生态移植包的版本号还带着 -ohos.N 平台后缀,直接把裸版本串喂给区间判定,会把 1.5.0-ohos.1 误当成 <1.5.0 的预发布,门禁当场误伤。
本文记录一个可真机运行的方案:把 SemVer 2.0.0 + npm 区间 + Maven 区间的判定引擎用 Kotlin 源码级移植进 KMP 工程,配上解析器、一句式策略漏洞库和 CycloneDX SBOM 输出,做成一个叫 SecBaseline(安全编码基线台) 的鸿蒙应用——门禁不过会红着眼拦住你,修复到线就放行。

图 1:移植自检屏上半。kotlin-semver 3.1.0 移植完成后,上游 25 条规范语料在 ohos 目标上「25/25 全部通过」,解析 3/3、比较 3/3、约束 5/5 分组逐条展开,每条都并排列出「期望 / 实得」。
一、先想清楚:门禁凭什么说话?
依赖审计看起来是「字符串比对」,真做起来是三层判断叠在一起:
- 收集:工程到底声明了哪些依赖、解析到了哪些版本。Gradle 侧的权威来源是
gradle/libs.versions.toml(Version Catalog),ohpm 侧的权威来源是oh-package-lock.json5(锁文件里的version字段才是最终解析结果,不能看oh-package.json5的区间声明)。 - 判定:把每个「包名 + 版本」喂给漏洞公告,公告里写的是区间(如
<1.5.0、[2.0,3.0)),需要一个能同时吃 npm 风格(^~>=1.0 <2.0)、Maven 风格([1.0,2.0))和纯 SemVer 的比较器。 - 裁决:汇总严重度分布,按门禁阈值(本工程默认「≥高危即拦」)给出 PASS/FAIL,并把理由落盘成机器可读的
gate-report.json,CI 直接消费。
这三层里,第 2 层是全部的地基。地基不稳——区间语义错了、平台后缀没处理——上面搭的 SBOM 再漂亮也是错的。
二、为什么源码移植 kotlin-semver,而不是依赖它?
SemVer 判定我不想自己写。社区里 z4kn4fein/kotlin-semver(MIT)是最接近「规范实现」的 Kotlin 库:解析、比较、npm 区间、宽松模式都有,且带 1000+ 条规范语料测试。
但直接 implementation("io.github.z4kn4fein:semver:3.1.0") 在鸿蒙生态有一个现实的绊脚石:它传递依赖 kotlinx-serialization。鸿蒙工程里序列化框架常常是 ABI 敏感项(本工程另一条线就在跟序列化版本碰撞较劲),为了一个版本号比较器拖进一整套序列化运行时,风险收益不成比例。
所以走了源码级移植路线(这在鸿蒙生态是常规操作,KMP 鸿蒙社区 CPF-KMP-CMP 的多个移植件都这么干):
- 从上游 tag
3.1.0(commit260a3816)取 16 个 Kotlin 源文件进semver/模块; - 剥掉
VersionSerializer/ConstraintSerializer两个文件——它们是唯一触碰 kotlinx-serialization 的地方; - 去掉上游构建脚本里的 explicitApi、dokka 等发布向配置;
- 包名保持
io.github.z4kn4fein.semver,发布为com.ohos.semver:semver:3.1.0-ohos.1,来源与改动全部记录在semver/UPSTREAM.json。
移植完之后没有急着写审计引擎,而是先把上游的 25 条规范语料做成 App 内的移植自检屏(图 1 那一页):完整版本串拆解、宽松模式下 v 前缀与缺位、非法输入返回 null 而不抛异常、SemVer 2.0.0 第 11 条优先级序列、构建元数据不参与优先级、0.1.0 < 0.1.1 的数值比较,逐项在 ohosArm64 真机上跑一遍。这一步很值——后面调试审计逻辑时,凡是版本语义出了问题,我可以放心地怀疑自己的新代码,而不是移植件。

图 2:同一自检屏的下半。^1.2.3 拒绝 2.0.0、~1.2.3 命中 1.2.9 拒绝 1.3.0、1.2.x 通配符、连字符区间 1.1.0 - 1.2.0、Maven 区间 [1.2.3,2.0.0)、^1.2.3 转 Maven 记法、CVE 区间 <1.6.0 命中 1.5.32 而放行 1.6.0,再加 3 条移植陷阱用例——后面审计引擎要依赖的语义面,这一屏基本铺完了。
顺手说一下这个版本号的黑色幽默:移植件自己就叫 3.1.0-ohos.1,它正是下一节要讨论的「-ohos.N 平台后缀陷阱」的活体标本。工程标题栏上那句 com.ohos.semver:semver:3.1.0-ohos.1 不是水印,是自首材料。
三、审计引擎:从两份清单到一张依赖表
3.1 两套生态,一个解析器门面
Gradle 工程的真相在 TOML 里:
[versions]
okhttp = "4.12.0"
[libraries]
okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
ohpm 工程的真相在锁文件 JSON5 里,packages 数组每条的 name + version 才是解析结果。两个格式一个也别想用正则糊弄——TOML 的字符串里能塞 = 和 #,JSON5 允许尾逗号和无引号键。做法是各写一个最小但完整的词法扫描器(TOML 约 200 行,JSON 迷你解析器约 300 行,全部 commonMain 纯 Kotlin),解析出统一的 Dependency(coordinate, version, source) 表。
真机界面上「输入清单」区如实列出每个来源与行数:libs.versions.toml(14 行)、oh-package-lock.json5(29 行)、oh-package.json5(12 行),合计 13 条依赖;依赖关系里点开「展开全部」,还能看到每一条的解析来源与归一化结果,而不是一个黑盒的「通过」。
3.2 一句式策略的漏洞库
漏洞公告做成了离线单条策略的形式(audit/AdvisoryDb.kt),长这样:
com.squareup.okhttp3:okhttp @ <4.9.1 => HIGH CVE-2021-0341 证书主机名校验缺陷
org.yaml:snakeyaml @ <2.0 => CRITICAL CVE-2022-1471 反序列化可RCE
@ 后是判定区间,直接复用第二部分移植的引擎。这样设计有三个考虑:真机上离线也能跑(不用等网络);每条命中在 UI 上能讲出完整的一句话,而不是一个光秃秃的 CVE 号;新增公告就是加一行字,不用动引擎。10 条公告覆盖 9 个坐标,足够演示门禁行为;工程里也留了把 GitHub Advisory 批量翻译成此格式的脚本位。
3.3 归一化:鸿蒙生态特有的坑,必须用 A/B 对照讲清楚
重点来了。鸿蒙生态移植件的版本号普遍长这样:1.5.0-ohos.1、3.1.0-ohos.1。按照 SemVer 规范,- 后面是预发布标识,预发布版本永远小于同名正式版——也就是说裸判定下 1.5.0-ohos.1 < 1.5.0 成立。如果有条公告是「okhttp <1.5.0 受影响」,那么 1.5.0-ohos.1 会被误判命中,实际上人家移植的是修好的 1.5.0。
对策是归一化:判定前先 withoutSuffixes() 剥掉预发布和构建元数据。但剥掉也有反向风险——如果某条公告只针对平台移植本身(比如 -ohos.1 的补丁引入了新问题),归一化就把这个信号洗没了。所以公告格式允许显式声明「只剥平台标记」,对这类公告归一化照做不误。
这种「正反都可能出错」的逻辑,最怕写完没人验证。UI 上我做了一个 A/B 同清单双跑对照:同一份输入清单,裸判定跑一遍、归一化跑一遍,两列数字并排,误报多少、消除多少一目了然。

图 3:本工程真实清单的判定结果。门禁通过、0/13 受影响;归一化对照里裸判定命中 2 次、归一化后 0 次、消除误报 +2。下方结论写得很直白:「未命中任何已知漏洞,区间判定全为『不满足』,可放行进入构建」——注意这 2 次命中全部是 -ohos.N 后缀造成的假阳性,不是真漏洞。
3.4 门禁落盘:让 CI 能接到结论
裁决结果不止于屏幕。两个产物写到应用沙箱的 audit/ 目录:
sbom-cyclonedx.json:CycloneDX 1.6 格式,直接喂 Dependency-Track / Trivy;gate-report.json:{ passed, threshold, violations[], reason },CI 读passed字段决定放行。
真机界面下滑即可看到「审计产物」区:目录路径 /data/storage/el2/base/haps/entry/files/audit 下,两个文件各挂一枚绿色的「已落盘」;旁边一行小字写明「SBOM 可直接喂给 Dependency-Track / Trivy,gate-report.json 供 CI 读取 passed 字段决定是否放行」。写文件走 PlatformFiles expect/actual:ohos 侧用 @ohos.file.fs 写 filesDir,JVM 侧写临时目录跑测试。整条链路没有一处依赖 Android 专用 API。
四、真机实测:拦截 → 修复 → 放行
图 4 是工程内置的「注入高危依赖」演示清单:把 4 个带已知 CVE 的坐标混进 8 条依赖。审计结果:1 严重、3 高危,4/8 受影响,门禁红色「不通过 / 构建应被阻断」;归一化对照显示裸判定 4 次命中、归一化后仍是 4 次、消除误报 0——这恰好反证了图 3 里那 2 次命中确实只是后缀误报,真命中是剥不掉的。命中明细按严重度排序,com.squareup.okhttp3:okhttp@4.9.0 顶着「严重」标签排在最前,并标注「声明来源:libs.okhttp」。

图 4:注入高危依赖后门禁拦截。阈值设为「≥高危」,1 严重 + 3 高危直接触发阻断,8 条依赖里 4 条受影响。
切到「修复对照」清单(版本抬到修复线,5 条依赖)再跑一次:0/5,门禁绿色「可进入构建」,耗时 1ms,归一化对照三格全 0。这个耗时值得说一句,全离线判定本来就是毫秒级,慢的是 IO 读清单。

图 5:修复对照清单。依赖清单(5)可「展开全部」查看每条的解析来源与归一化结果,结论同样是「未命中任何已知漏洞」。
同一工程、两种结局的对比,就是这类工具存在意义的全部论证。
五、总览:三条能力线的汇流
审计屏之外,总览页把所有信息收成一个 100 分安全基线分:扫描依赖 13、受影响 0、消除误报 2,四个格子里 0 严重 / 0 高危 / 0 中危 / 2ms 耗时。下方「三条能力线」如实标注进度——依赖与漏洞审计「已接入」,WebView 配置红线、权限最小化仍是「待接入」(这是 M3 的工作,本系列下篇展开);再往下是 semver 移植自检 25/25 与公告库快照(10 条:2 严重 / 5 高危 / 3 中危 / 0 低危)。

图 6:总览页。分数、能力线接入状态、自检通过数、公告库分布一屏收齐,离线也能看——内置基线快照,断网照跑,线上环境再换成拉取 GitHub Advisory。
六、踩坑清单(都能复现,避坑请抄)
-ohos.N后缀是预发布语义。裸 SemVer 下1.5.0-ohos.1 < 1.5.0成立,门禁会误伤修好的版本;判定前必须归一化。反向地,纯「只剥平台标记」的公告是例外,规则库里要给它单独开口。- 归一化不是万能药,要能自证。A/B 同清单双跑是最便宜的自证:图 3 的
2 → 0,+2证明消掉的是误报,图 4 的4 → 4,0证明真漏洞没被洗掉。只看「归一化后 0 命中」就宣布安全,是把工具用成了安慰剂。 - TOML 别用正则。
{ module = "...", version.ref = "..." }内联表里逗号和引号的组合能写死任何正则;老老实实写词法扫描,200 行而已。 - ohpm 要读锁文件,不读清单。
oh-package.json5里是区间声明,不是解析结果;审计的输入必须是oh-package-lock.json5的packages[].version。面向声明做审计等于猜。 - kotlinx-serialization 是移植依赖审计库时的最大绊脚石。剥掉 Serializer 两个文件后 kotlin-semver 零外部依赖,鸿蒙工程随便进。
- 移植件先自检再使用。上游 25 条规范语料做成 App 内自检屏,跑绿之前一行业务代码都别写——「引擎错还是业务错」的界分一分价钱一分货。
- 离线 SBOM 优先。真机演示、地铁里调试、内网 CI 都不吃网络的亏;公告库做成一句式策略文本,版本控制友好,diff 一眼可见。
[1.0,2.0)和>=1.0 <2.0是两种方言。Maven 的边界括号语义和 npm 的合取语义在移植库层面统一成同一棵区间树,业务层只面对一种模型,否则每个公告得写两遍。
七、结语
依赖审计在鸿蒙生态不再是「等云端工具适配」的被动题:区间判定引擎 16 个文件,解析器两个,公告库一行一条,门禁两个 JSON 落盘。全部 commonMain 纯 Kotlin,ohosArm64/ohosX64 双架构毫秒级出结果,36 个 JVM 用例兜底语义。工程已开源到 AtomGit(oh-tpc/kmp-ohos-sec-baseline)。
这只是 SecBaseline 三条能力线的第一条。下篇聊另外两条更有戏剧性的:WebView 配置红线——攻击串是真的打进一个 Web 组件里跑的;以及权限最小化——为什么注释里的一行权限名会把审计结论整个带反。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)