10 分钟跑通 Erosion-CN:单仓部署的最小可行路径

原创2026-11-11 20:34:151,459 阅读

10 分钟跑通 Erosion-CN:单仓部署的最小可行路径

Erosion-CN 是一个针对 iOS / iPadOS 的 MobileGestalt 系统配置研究工具箱,它把「读取系统缓存 → 解析二进制槽位 → 原位覆盖写入 → 读回校验」整条链路封装进一个 Xcode 工程里。对大多数想跑一遍的人而言,最大的障碍不是理解原理,而是「代码在哪、怎么编、编出来算不算成功」。这个仓库的特别之处在于:构建、签名、产物打包全部收敛到一个脚本里,仓库本身即可自洽,不依赖任何子模块或私有 SDK。

本文只做一件事:把「从 git clone 到设备上出现三条关键日志」这段最短路径讲清楚,并给出两个能真正证明它可用的验证点。先说明前提——本项目仅面向本人持有设备的系统安全研究,修改系统缓存存在风险,请先做完整备份。

一、拉取与目录确认:先看清楚仓库里给的是什么

git clone https://github.com/Kianuni/Erosion-CN.git
cd Erosion-CN
ls

顶层只有 8 个可见条目,没有 Pods/、没有 submodules、没有 Vendor/:

路径 作用
Erosion/ 唯一的 App target 源码根目录
Erosion.xcodeproj/ 工程文件,含 project.pbxproj
ipabuild.sh 从编译到 .ipa 打包的完整流水线
.github/workflows/build.yml 手动触发的 CI 构建
USAGE_GUIDE.md / RESTORE_CHA.md 安装使用与恢复出厂说明

源码规模可以直接数出来:59 个 .swift 文件,加上 4 个 C / Objective-C 文件(bad_query.c、pathleak.m、worse_query.m、MGImageReader.m)。后四个正是这个项目的「地基」——Swift 层通过一份统一的桥接头文件 bridge.h 引入它们,桥接头里还额外声明了 SecTaskCreateFromSelf 与 SecTaskCopyValueForEntitlement 这两个未公开签名 API,以及 LSApplicationWorkspace:

#import "Exploits/bad_query.h"
#import "Exploits/worse_query.h"
#import "Exploits/pathleak.h"
#import "Tweaks/MobileGestalt/MGImageReader.h"

typedef struct CF_BRIDGED_TYPE(id) __SecTask *SecTaskRef;
SecTaskRef _Nullable SecTaskCreateFromSelf(CFAllocatorRef _Nullable allocator) CF_RETURNS_RETAINED;

在动手构建前,需要先接受三个由工程配置决定的事实,它们直接决定你能否在 10 分钟内完成构建:

  1. 部署目标是 iOS 26.0。 project.pbxproj 中 IPHONEOS_DEPLOYMENT_TARGET = 26.0、MARKETING_VERSION = 0.6.2、CURRENT_PROJECT_VERSION = 11、PRODUCT_BUNDLE_IDENTIFIER = com.jbdotparty.Erosion,TARGETED_DEVICE_FAMILY = "1,2" 意味着 iPhone 与 iPad 共用同一份产物。README 建议的 Xcode 26 / 27 并非虚指。
  2. 工程采用文件夹同步而非显式文件列表。 PBXNativeTarget 里是 fileSystemSynchronizedGroups = (Erosion),源码目录由文件系统自动同步,因此新增文件无需改工程。这一特性要求较新的 Xcode,也意味着你用旧版 Xcode 打开会看到一个空壳 target。
  3. 唯一的外部依赖是 SPM 包 ZIPFoundation,upToNextMajorVersion 0.9.20,被 AppDataBackupView.swift、KeypadManager.swift、PBHandler.swift 等 6 个文件引用。首次构建时必须有网络完成包解析,这是「10 分钟」里最容易超时的一环。

另外要提醒一句脚本本身的破坏性:ipabuild.sh 开头就是 rm -rf build 并删除仓库根目录下所有 *.ipa。不要在还留着上一版产物做对比的目录里随手执行。

二、最小启动命令与首次成功的判断标准

2.1 一条命令跑完

chmod +x ipabuild.sh
./ipabuild.sh

如果只是想先确认工程本身能否被解析、scheme 叫什么,可以额外先跑一次:

xcodebuild -list -project Erosion.xcodeproj

这一步值得单独执行。仓库里并没有提交 Erosion.xcscheme——.gitignore 明确忽略了 xcshareddata/ 与 xcuserdata/,所以 scheme 依赖 Xcode 的自动创建。先跑 -list 可以让自动 scheme 生成并落盘到用户目录,避免第一次 xcodebuild 因为「找不到 scheme Erosion」直接失败。

需要调试构建时,脚本支持一个参数:

./ipabuild.sh --debug

它会切到 Debug 配置,并把产物改名为 Erosion_v0.6.2_zh-Hans.debug.ipa。

2.2 脚本到底做了什么

读懂 ipabuild.sh 比读构建日志更快。它的流程只有五步:

第一步,从工程里反读版本号,拼出产物名。

APP_VERSION=$(grep -m1 'MARKETING_VERSION =' "$APPLICATION_NAME.xcodeproj/project.pbxproj" \
  | sed -E 's/.*= *([^;]+);/\1/' | tr -d '[:space:]')
IPA_NAME="${APPLICATION_NAME}_v${APP_VERSION}_zh-Hans.ipa"

版本号只有一个来源,就是 project.pbxproj,改完版本不需要同步任何脚本常量。

第二步,完全关闭签名的编译。 关键在于这组参数:

xcodebuild -project "$WORKING_LOCATION/$APPLICATION_NAME.xcodeproj" \
    -scheme "$APPLICATION_NAME" \
    -configuration Release \
    -derivedDataPath "$WORKING_LOCATION/build/DerivedDataApp" \
    -destination 'generic/platform=iOS' \
    build \
    CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGN_ENTITLEMENTS="" CODE_SIGNING_ALLOWED="NO" \
    ASSETCATALOG_COMPILER_OPTIMIZATION=space DEPLOYMENT_POSTPROCESSING=YES \
    STRIP_SWIFT_SYMBOLS=YES SEPARATE_STRIP=YES STRIP_STYLE=all

CODE_SIGNING_ALLOWED=NO 意味着不需要 Apple ID、不需要开发者团队、不需要描述文件,这是「10 分钟」能成立的根本原因;后半段的 strip 优化则用来压缩 Swift 符号体积。

第三步,剥离可能残留的签名。

codesign --remove "$TARGET_APP"
rm -rf "$TARGET_APP/_CodeSignature" "$TARGET_APP/embedded.mobileprovision"

第四步,重新注入 entitlements。 优先用 ldid,否则退化为 ad-hoc 签名:

if command -v ldid >/dev/null 2>&1; then
    ldid -S"$WORKING_LOCATION/Erosion/Erosion.entitlements" "$TARGET_APP"
else
    codesign --force --sign - --entitlements "$WORKING_LOCATION/Erosion/Erosion.entitlements" \
      --generate-entitlement-der --timestamp=none "$TARGET_APP"
fi

注入内容来自 Erosion.entitlements,只有一个键:

<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.jbdotparty.Erosion.WQ</string>
</array>

这解释了为什么整个项目「离开 App Group 就无法工作」——沙盒逃逸需要一个可写的共享容器作为跳板。

第五步,组 Payload 并压缩成 IPA,zip -9vr、mkdir Payload、cp -r Erosion.app Payload/,最后 mv 到仓库根目录并删除中间 build/ 目录。

2.3 三层成功判据

脚本 set -e,任何一步失败都会中断,所以「退出码为 0」只是第一层。真正的成功要三层都过:

第一层,脚本打印出最终产物路径。

[*] All done, cleaning up...
[*] Output IPA: /path/to/Erosion-CN/Erosion_v0.6.2_zh-Hans.ipa

第二层,IPA 结构正确。 解包检查可执行文件与资源是否齐全:

unzip -l Erosion_v0.6.2_zh-Hans.ipa | head -20
unzip -o -q Erosion_v0.6.2_zh-Hans.ipa -d /tmp/eros
codesign -d --entitlements :- /tmp/eros/Payload/Erosion.app 2>/dev/null

预期看到 Payload/Erosion.app/Erosion,以及 entitlements 里那条 group.com.jbdotparty.Erosion.WQ。若 codesign -d 输出为空(ldid 注入的签名在某些 macOS 版本上不被 codesign 完整回读),改用 ldid -e 再验证一次即可。这一步是很多人踩空的地方:IPA 能装、能开,但 App Group 没进去,于是后面所有功能都「看起来正常、实际全部失败」。

第三层,装到实机后日志出现三行。 见下一节。

2.4 时间预算与最常见的四类卡点

阶段 典型耗时 主要变量
clone 仓库 < 1 分钟 网络
首次 xcodebuild(含 SPM 解析) 2–5 分钟 ZIPFoundation 拉取速度
strip + 去签名 + 重签 + 打包 < 30 秒 设备架构切片数量
侧载安装 1–2 分钟 签名工具与 Apple ID 二次验证

对应的四个高频卡点:一是机器上根本没有 xcodebuild(Linux / Windows 上无法完成这条路径);二是 scheme 未生成,先 -list;三是 SPM 解析失败,重跑一次或检查代理;四是签名工具不保留 App Group,产物装上了但跑不出功能。

三、装到设备:签名是第二步构建

安装不是「装完就能用」,而是让 entitlements 在设备上真正生效的第二次构建。README 与 USAGE_GUIDE.md 都点名要求:使用支持保留或注入 App Group 的自签工具(SideStore / AltStore / Feather / Sideloadly / Impactor / iLoader),或带 App Group 权限的开发者证书。

一个容易被忽略的细节是覆盖安装:升级版本时不要先卸载旧版。旧版沙盒里躺着首次运行生成的 OriginalGestalt.plist 与 OriginalGestalt.sha256,这是后续「还原原始备份」唯一的凭据;卸载等于自己销毁回滚路径。

装完后首次启动,日志区应当出现三条信息(对应 ErosionApp.swift 的 onAppear):

[*] Erosion v0.6.2 (zh.11 汉化修复版)
[*] 运行环境:iOS 27.2,设备标识符:iPhone18,1 (24C…)
(wq) 当前使用 App Group:group.com.jbdotparty.Erosion.WQ

第二行的 zh.11 汉化修复版 来自全局变量 build("zh.\(AppInfo.appBuild) 汉化修复版",appBuild 即 CFBundleVersion),可以用来确认你装的是本分支而不是上游英文版。第三行最关键:它说明 App Group 容器已经拿到,沙盒逃逸的落点存在。

这个识别过程并非写死,而是两级回退。核心在 WorseQuerySwift.swift:

if let task = SecTaskCreateFromSelf(nil),
   let value = SecTaskCopyValueForEntitlement(task, "com.apple.security.application-groups" as CFString, nil),
   let groups = value as? [String], !groups.isEmpty {
    signedGroups = groups
    print("(wq) SecTask 读取到 \(groups.count) 个已签名 App Group")
} else if let fallbackGroups = Self.readMachOAppGroups(), !fallbackGroups.isEmpty {
    signedGroups = fallbackGroups
    print("(wq) Mach-O 签名段解析到 \(fallbackGroups.count) 个 App Group")
}

第一级通过 SecTask 读运行时签名;第二级更硬核——直接映射自身可执行文件,扫描 LC_CODE_SIGNATURE,按 0xfade0cc0(超级 blob)与 0xfade7171(entitlements blob)两级魔数解析出真实的 App Group 列表,并支持 fat 二进制按 cputype / cpusubtype 精确挑选当前架构切片。最后才用 fm.containerURL(forSecurityApplicationGroupIdentifier:) 逐个试探,选出第一个真正可打开的容器。这段代码的存在意味着:即便你的重签工具把 group 名改成了别的,应用也能自己找到。

还有一处与版本强相关:在 iOS 26 上,访问 /var/mobile/Containers/Shared/AppGroup 需要走一条不同的 worse_query 调用分支(第三个参数传 true);iOS 27 及以上走默认分支。这是 grantAccess 里唯一的系统版本特判。

顺带说明一个「兼容性判断已被放弃」的现实。isSupported() 现在是无条件 return true,原来的版本区间判断整段被注释掉,真实门控只剩两处:raveSupported()(majorVersion >= 27)决定「MobileGestalt 修改」入口是否出现,以及每次 grantAccess 的实际返回值。所以如果你在 iOS 26 设备上找不到 Gestalt 入口,那是设计如此,不是构建失败。

四、跑通之后先验证哪两个功能才算真的可用

界面能开、日志能滚动都不算可用。真正要验证的是两条互相独立的链路:能不能拿到沙盒外的文件访问权,和能不能正确解析本机的缓存布局。前者决定功能能不能落地,后者决定落地后会不会把系统写坏。

验证一:文件浏览直通 MobileGestalt 缓存目录

路径是「文件浏览」→「快捷访问」→「MobileGestalt 缓存目录」。这一项在 FMRootView.swift 里被配置为 shouldGrant: true,目标目录由 MGURL.fsGestaltURL.deletingLastPathComponent() 推导:

static let fsGestaltURL = URL(fileURLWithPath:
  "/private/var/containers/Shared/SystemGroup/systemgroup.com.apple.mobilegestaltcache/Library/Caches/com.apple.MobileGestalt.plist")

进入时 FileBrowserView 会先判断写权限,写不了才去申请授权;拿到句柄后再以 pathleak 枚举目录(isContainer 模式)。判断标准很明确:目录能列出、com.apple.MobileGestalt.plist 能看到、能进入子目录,就算这条链路通了。

失败时会给出确定性错误码,这在排障时比「无法访问」有用得多,均来自 grantAccess 的返回映射:

返回值 含义
-1 无法访问 App Group
-2 解析系统函数失败
-3 创建查询句柄失败
-4 创建符号链接失败
-5 沙盒查询被拒绝
-6 内核拒绝下发沙盒扩展令牌
-255 目标路径不存在

如果 -1,问题在签名(回到上一节检查 entitlements);如果是 -5 / -6,说明当前系统的沙盒策略已经变了,worse_query 在你的版本上失效,此时任何后续操作都不必尝试。

验证二:CacheData 动态解析是否「精确匹配本机缓存布局」

路径是「功能修改」→「MobileGestalt 修改」。这个页面加载时会做三件事,验证的就是这三件是否都成立。

第一件,首次运行自动落盘原厂备份并附完整性摘要。 mgLoadData() 在发现备份不存在时会调用 mgSaveOriginalBackupWithDigest,写入 OriginalGestalt.plist 的同时计算 SHA-256 存到 OriginalGestalt.sha256,两个文件都被打上 isExcludedFromBackup = true,防止 iCloud 或换机迁移把旧设备的缓存带进新设备:

func mgSaveOriginalBackupWithDigest(_ data: Data) throws {
    try data.write(to: MGURL.savedGestaltURL, options: .atomic)
    mgExcludeFromCloudBackup(MGURL.savedGestaltURL)
    let hex = mgComputeSHA256Hex(data)
    try Data(hex.utf8).write(to: MGURL.savedGestaltSHA256URL, options: .atomic)
    mgExcludeFromCloudBackup(MGURL.savedGestaltSHA256URL)
}

验证方式:进入页面后到「⋯ → 高级设置 → 数据备份与导出」,确认「导出原始备份」可点,说明备份已生成。

第二件,本机 libMobileGestalt.dylib 零硬编码偏移解析。 这是整个项目技术上最核心的一段,在 MGCacheLayout.swift。它不查任何机型表,而是只读扫描内存中已加载的系统库,规则写在注释里:

/// Scans modern 64-byte MobileGestalt query descriptors:
/// +0x00: pointer to 22-char obfuscated key string (canonical 48-bit user VA)
/// +0x3A: signed Int16 cache slot index
/// +0x3C: UInt32 query type (11 = Boolean)

流程是:从 __cstring 里捞出所有 22 字符的混淆键(字符集限定在字母数字与 + /),建立「虚拟地址 → 键名」映射;再以 8 字节步长扫 __const,剥掉 arm64e PAC 高位(rawPtr & 0x0000_7FFF_FFFF_FFFF)后反查键名,读出槽位号与查询类型。三重门控决定了它「宁可拒绝也不猜」:CacheUUID 必须全局唯一,槽位数必须满足 CacheData.count == slotCount * 9,目标槽位的 validity 字节必须为 1 且 8 字节内填充全零。

页面上这一项的可视化结果就是那句绿色文案「已精确匹配本机缓存布局」,点右侧「查看偏移」会弹出诊断报告:

状态:✅ 已精确匹配本机系统库与缓存文件
CacheUUID:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
总槽位数:NNN 个(共 NNN*9 字节)
green-tea:槽位 N,偏移 0xNNN(有效位 0xNNN),当前值 = false
not-green-tea:槽位 N,偏移 0xNNN(有效位 0xNNN),当前值 = true

如果这里不是绿色,就不要继续。 页面会把两个二进制缓存开关直接 .disabled(true),并在下方用红字给出 cacheResolutionFailureReason()。这是有意设计的安全措施:解析没通过时,任何写入请求都会被 validateTransition 拦死。

第三件,写入链路的护栏是否就位。 这一项不需要真的改东西,看两处即可:写入前会弹「变更对比预览」,逐条列出键值变化;「高级设置」里那一行显示为「安全原位写入 + 物理刷盘 (F_FULLFSYNC) —— 已强制锁定」。后者由一个迁移标记在启动时强制打开:

UserDefaults.standard.register(defaults: ["mgWriteAtomically": true, "maxInode": 15000000])
if !UserDefaults.standard.bool(forKey: "mgAtomicDefaultMigrated") {
    UserDefaults.standard.set(true, forKey: "mgWriteAtomically")
    UserDefaults.standard.set(true, forKey: "mgAtomicDefaultMigrated")
}

这条默认值不是小事。上游版本在没有手动切换过开关时,mgWriteAtomically 默认为 false,于是走临时文件 replaceItemAt,破坏系统缓存文件的 Inode 与属主权限,重启即被系统丢弃重建。本分支改成无条件走 WriteHelpers.swift 里的原位协议:

// 1. Overwrite directly from offset 0 via pwrite (NEVER ftruncate to 0 first!)
try pwriteAll(fd, data, startOffset: 0)

// 2. Only shrink tail if new payload is shorter than original payload
if data.count < og.count {
    guard ftruncate(fd, off_t(data.count)) == 0 else { throw fileWriteErr.truncate(errno: errno) }
}

// 3. Flush APFS + NVMe controller cache to physical NAND
guard fullFsyncSafe(fd) else { throw fileWriteErr.sync(errno: errno) }

// 4. Full descriptor readback byte-for-byte verification

注意第 1 步的括号注释,它点明了一个非常具体的失败模式:先 ftruncate(fd, 0) 再写,会在闪存上留下一个真实的 0 字节窗口,此刻断电就是空文件。上面这段代码用「直接从偏移 0 覆盖 + 写完才裁尾 + F_FULLFSYNC 刷盘 + 逐字节读回 + 失败原位回滚」把这个窗口消掉了。上层 mgWriteDetailed 还会再做一次独立的磁盘读回校验,不一致就调用同一个函数把原始字节写回去。

所以「可用」的最终判据是三条同时成立:文件浏览能直通缓存目录;Gestalt 页面显示绿色「已精确匹配本机缓存布局」并能弹出偏移诊断;高级设置里原位写入为「已强制锁定」。三者齐备,你手上这个构建才是一个可以真正开始做研究的基线;缺任何一条,都只是一个能启动的壳。

最后提一句恢复路径,这与「跑通」同样重要:任何改动都可以通过关闭对应开关重新应用,然后在「⋯ → 还原原始备份」中回到原厂状态(还原前会强制核对 SHA-256、CacheVersion、CacheUUID、CacheData 长度与硬件 ProductType);若备份本身已被污染,则用「清除并重建缓存」删除系统缓存文件,重启后由 mobilegestaltd 依据主板出厂数据重新生成。把这条退路在动手前就走一遍,是比任何加速技巧都值钱的一步。

登录后查看全文
Erosion-CN