10 分钟跑通 Erosion-CN:单仓部署的最小可行路径
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 分钟内完成构建:
- 部署目标是 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 并非虚指。 - 工程采用文件夹同步而非显式文件列表。
PBXNativeTarget里是fileSystemSynchronizedGroups = (Erosion),源码目录由文件系统自动同步,因此新增文件无需改工程。这一特性要求较新的 Xcode,也意味着你用旧版 Xcode 打开会看到一个空壳 target。 - 唯一的外部依赖是 SPM 包 ZIPFoundation,
upToNextMajorVersion0.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 依据主板出厂数据重新生成。把这条退路在动手前就走一遍,是比任何加速技巧都值钱的一步。