HermesEnabler 贡献指南:如何为新的 watchOS 构建添加 MobileGestalt 偏移表与沙箱策略

原创2026-11-13 11:09:211,830 阅读
文章标签:移动开发原生移动逆向工程

HermesEnabler 贡献指南:如何为新的 watchOS 构建添加 MobileGestalt 偏移表与沙箱策略

HermesEnabler 是一个让任意 Apple Watch 解锁 Hermès 独占表盘的开源项目。本文是一份面向新手的贡献指南:教你如何为新出现的 watchOS 构建完成物理 OTA 验证、填写 MobileGestalt 偏移表(MGOffsets.plist)与沙箱策略检查,让你的 PR 一次通过。

HermesEnabler 项目效果:Apple Watch 上显示 Hermès 表盘

一枚运行 HermesEnabler 后解锁 Hermès 表盘的 Apple Watch。你的贡献,就是让下一个 watchOS 版本的用户也能看到这一幕 ⌚

为什么每个 watchOS 构建都要有独立的偏移表

HermesEnabler2 的工作原理,是修改手表上 MobileGestalt 缓存(系统用来回答"我的设备支持什么"的缓存文件)。这个缓存包含三个关键字段:

字段 作用
CacheData 二进制数据块,每个键的值存放在随构建变化的固定字节偏移处
CacheExtra 字典形式的覆盖项,使用不透明的"加密键"标识
CacheUUID 布局指纹,应用用它判断缓存是否属于预期构建

关键点:同一个营销版本号(如 27.2)对应的内部构建号(如 24S132)才是布局的真正索引。研究文档中 24R359 的条目就是从相邻构建 24R364 复制的假设值——它的 RecoveryVerified 标记为 false,因为缺少独立的物理 OTA 验证。这正是本文要帮你避免的坑。

完整原理见 Research/MobileGestalt/README.md,"Adding a build" 一节明确写道:不要仅因营销版本号相近或缓存长度相同就复制偏移量。

准备工作:克隆仓库并熟悉核心文件

git clone https://gitcode.com/GitHub_Trending/he/HermesEnabler

先通读以下 4 个文件,它们构成你的"贡献地图" 🗺️:

文件 作用
MGOffsets.plist ⭐ 偏移表:每个构建的缓存布局与描述符索引
MGDefaults.plist 每个构建的激活值与验证边界
BQCore.m 沙箱逃逸与 MobileGestalt 读写核心实现
Research/OTA/README.md 可复现的物理 OTA 分析工作流

以已验证的 24R364 条目为模板(见 MGOffsets.plist 第 45-111 行),一个完整条目包含:

  • CacheUUID / CacheDataLength:缓存指纹与总长度
  • DeviceBrandOffset / ScreenClassOffset:两个数值键的字节偏移(Hermès 与 Ultra 表盘分别依赖它们)
  • PresenceBase:布尔能力"存在位"的起始偏移,第 index 个能力的存在位位于 PresenceBase + index
  • Indexes:8 个布尔能力(AOD、Action Button、Double Tap 等)的描述符索引
  • AdditionalIndexes:13 个附加能力索引(如心率、罗盘)
  • RecoveryVerified:只有当恢复路径的证据也成立时才设为 true

第一步:锁定物理构建并下载对应 OTA

  1. 确定目标 watchOS 构建号(如 24T123)与具体机型(如 Watch8,1)。营销版本号只是外观,构建号才是布局索引。
  2. 从 Apple 更新服务获取该机型 + 构建的全量物理 OTA(full OTA),单独保存其来源与预期 SHA-256。
  3. 校验下载完整性——这一步只能证明"文件没下错",不是对二进制语义的证明:
shasum -a 256 "$OTA_PATH"

完整数据集说明见 Research/OTA/README.md。

第二步:提取并分析 libMobileGestalt.dylib

使用社区工具 ipsw 提取 dyld 共享缓存中的目标动态库:

ipsw ota extract "$OTA_PATH" --key-db "$KEY_DB_PATH" --dyld --confirm --output "$OUTPUT_DIR"
ipsw dyld extract "$DYLD_CACHE_PATH" libMobileGestalt.dylib --slide --output "$OUTPUT_DIR/mg"

然后对提取出的 libMobileGestalt.dylib 做静态分析,记录:

  • 选中架构(arm64e)与描述符索引
  • DeviceBrand、main-screen-class 的索引 → 换算出 8 字节值槽偏移与存在位偏移
  • 8 个主布尔键 + 13 个附加键的索引
  • 回调函数的输入来源(设备树属性?其他 MG 答案?机型检查?)

⚠️ 注意:main-screen-class 的回调会经由全局路径读取 MainScreenStaticInfo,分析时务必追踪其依赖链。

第三步:填写偏移表与默认值条目

将分析结果填入两个 plist:

MGOffsets.plist —— 按上文"核心文件"一节列出的字段逐项填写。若某个描述符在你的二进制中不存在(如 24R5315i 缺少两个附加描述符),省略它,不要臆造。

MGDefaults.plist —— 填写:

键 含义
MaxDeviceBrand DeviceBrand 的验证上限(如 2),是校验边界,不是写入值
HermesEnabledDeviceBrand Hermès 激活覆盖值,通常为 1
UltraEnabledScreenClass / UltraScreenClassOptions Ultra 表盘的屏幕类别,29 必选;38 仅在你的构建完成了 ClockKit 静态分析后才提供

38 这个备选值的门槛很高:需要验证 ClockKit 中 -<a href="https://link.gitcode.com/i/7dcb4748443cd4848ac4b2b3619111b6" target="_blank">CLKDevice _loadDeviceInfo] 的屏幕类别映射(29 → size 6,38 → size 9,且 isUltra 谓词接受对应类别)。参考 [Research/WatchFaces/README.md。

第四步:核对沙箱策略

HermesEnabler2 运行在严格的 App 沙箱内,要写入位于沙箱外的 MobileGestalt 缓存,必须借助 BQCore.h 定义的"沙箱逃逸租约":通过 MCM(containermanager)查询获取沙箱扩展 token,临时获得对目标容器的访问权,用完立即释放。

新增构建时需要关注的策略差异:

  • App Groups 权限:应用依赖 HermesEnabler2.entitlements 中的 application-groups 权限。它决定了逃逸的 class-1 路径是否可用。
  • class-2 父目录回退:BQCore.m 中注释说明,部分构建允许重命名应用自身的 Library 目录,部分构建会被 sandbox 直接杀掉进程,因此该回退默认关闭,且带崩溃保护标志。
  • 子路径符号链接策略:在 Library/Caches 内放置临时符号链接再请求 MCM 解析,是最温和的尝试路径。

如果你手头有实机设备,验证新构建上的实际行为并记录结果:逃逸策略是否全部失效、哪条路径成功、bqtool.log 的关键行。这是你 PR 中最有说服力的证据。

第五步:跑测试与构建

提交前,两条命令缺一不可:

clang -std=c11 -Wall -Wextra -Werror tests/BQRecoveryValidationTests.c -o /tmp/hermes-recovery-tests
/tmp/hermes-recovery-tests

单元测试覆盖了缓存槽位比对、DeviceBrand 解析、按钮列表解析等核心逻辑(见 tests/BQRecoveryValidationTests.c)。接着执行 watchOS 构建:

xcodebuild -project HermesEnabler2.xcodeproj -scheme HermesEnabler2 -configuration Debug -sdk watchos -destination 'generic/platform=watchOS' CODE_SIGNING_ALLOWED=NO build

记住:这些检查不能验证私有 API 访问、缓存写入或真机恢复行为——如有实机测试结果,请在 PR 中单独说明。

提交前自检清单 ✅

  • [ ] 偏移来自本构建自己的物理 OTA 提取,而非相邻构建复制
  • [ ] CacheUUID、长度、8 个主索引、13 个附加索引逐一比对过
  • [ ] 记录了实际检查的架构与机型(24S132 中 Watch7,11 与 Watch8,1 提取出的库哈希就不同)
  • [ ] RecoveryVerified 按证据诚实设置,而非顺手写 true
  • [ ] 沙箱策略行为(若实测)已记录
  • [ ] 隐私红线:绝不把设备的 MobileGestalt 备份、序列号、地区数据发布到研究材料中 🚫

写在最后

HermesEnabler 的研究文档反复强调一个原则:"模板、编译成功、UUID 相同"都不等于功能可用。每一条偏移背后都是一次可复现的静态分析;每一份 PR 的证据标签(代码 / 静态分析 / 运行时观测)都应清晰可查。保持这种严谨,你的构建条目就会像 24R364 那样,成为后来者可以放心引用的基准。

相关文档:Research 总览 · 恢复与备份研究 · 中文 README

登录后查看全文
HermesEnabler