如何把DuckDetector环境检测集成到你自己的App:SDK AAR嵌入与进程钩子接入分步指南
如何把DuckDetector环境检测集成到你自己的App:SDK AAR嵌入与进程钩子接入分步指南
DuckDetector 是一款在设备端运行的 Android 环境完整性检测工具,覆盖 root、Hook、Bootloader、SELinux、虚拟化、TEE 认证等环境风险信号。它把全部检测器、原生探测库与后台辅助服务打包成一个无 UI 的 SDK AAR,让你的 App 只需完成"构建 AAR → 添加依赖 → 调用扫描 API"三步,即可集成本地环境检测能力。本文带你分步走完 SDK AAR 嵌入与进程钩子接入的全流程,仓库内还附有一个仅依赖该 AAR 的完整示例工程 samples/sdk-consumer 可供对照。
📦 DuckDetector SDK 是什么?
SDK 就是"去掉了界面的 DuckDetector":所有检测器、libduckdetector.so 原生库、zygote preload 与隔离辅助服务,全部融合进一个 AAR 文件。由于官方 App 与 SDK 构建自同一批模块,两者执行完全相同的探针、产出完全相同的结构化报告,官方集成文档见 docs/guides/sdk-integration.md。
嵌入前请确认你的工程满足以下要求:
| 要求 | 值 |
|---|---|
minSdk |
29(Android 10+) |
compileSdk |
37 及以上(AAR 的 minCompileSdk) |
| Kotlin | 2.2 及以上 |
| ABI | arm64-v8a、armeabi-v7a、x86、x86_64 |
| 仓库 | SDK 本地仓库 + google() + mavenCentral() + jitpack(用于腾讯 soter-core) |
第 1 步:构建并发布 SDK AAR
克隆仓库(如已有本地副本可跳过):
git clone https://gitcode.com/gh_mirrors/du/Duck-Detector-Refactoring
然后执行发布命令:
./gradlew :sdk:aar:publish
AAR 会以 com.eltavine.duckdetector:duckdetector-sdk:0.0.0-SNAPSHOT 坐标发布到 sdk/aar/build/repository,需要自定义版本可加参数 -Pduckdetector.sdk.version=<版本号>。构建过程会自动运行 verifySdkAar 校验——若有 headless 模块缺失或被 UI 库污染,发布会直接失败,保证产物干净。构建配置见 sdk/aar/build.gradle.kts,Nightly 发布包中同样附带按 commit 命名的 SDK AAR。
第 2 步:在自己的工程中嵌入 AAR
在 settings.gradle.kts 中注册 SDK 本地仓库:
dependencyResolutionManagement {
repositories {
maven(url = file("<path to>/sdk/aar/build/repository"))
google()
mavenCentral()
maven(url = "https://jitpack.io")
}
}
在 app/build.gradle.kts 添加依赖:
implementation("com.eltavine.duckdetector:duckdetector-sdk:0.0.0-SNAPSHOT")
接下来什么都不用写:AAR 的清单会通过 manifest merger 自动带入 SDK 的服务、Native Root 的触发器以及 android:zygotePreloadName 指向的 preload 类。SDK 自身不申请任何权限,你的宿主 App 决定进程能看到什么——这一点在第 4 节展开。
第 3 步:三行代码调用扫描 API
核心入口是 sdk/runtime 中的 DuckDetector 对象,最小用法如下(完整示例见 ScanActivity.kt):
val results: List<DetectorResult> = DuckDetector.scan(context) // 全部检测器并发执行
DuckDetector.results(context).collect { result -> show(result) } // 逐个流式接收
val su = DuckDetector.detectors.first { it.id == DetectorId("su") } // 按 id 取单个检测器
每个 DetectorResult 携带 id、status 和 App 导出的同一份结构化 report。请像官方 App 一样这样解读状态:
status.severity |
含义 |
|---|---|
DANGER / WARNING |
观察到证据,报告说明看到了什么 |
ALL_CLEAR |
探针正常运行且未命中证据,不代表设备未被修改 |
INFO + SUPPORT |
该探针在此设备不受支持或不可用 |
INFO + ERROR |
检查失败,报告说明原因 |
注意:结果是启发式诊断信号,不是"设备安全"的判决书。
🔗 进程钩子接入:让环境检测证据采全
部分证据只能在进程生命周期的特定时机捕获,对应三个钩子。缺了钩子,所有检测器照样能跑,但依赖它们的证据只会报"不可用/失败",而绝不会误报为"干净"。
钩子 1:App zygote 预加载(自动接入)
AAR 清单已将 DuckDetectorZygotePreload 写入 android:zygotePreloadName,manifest merger 会把它带给你的宿主应用,无需任何声明。它会在任何隔离进程从 app zygote fork 之前,依次执行各检测器的 zygote 工作(如 Native Root 的 throne-hunt 监听)并采集 SELinux 上下文有效性证据——没有它,SELinux 与 LSPosed 载体会把 app zygote 证据报为不可用。
如果你的 App 已有自己的 ZygotePreload,merger 会报冲突而不是静默丢弃,此时保留自己的类并用 tools:replace="android:zygotePreloadName" 覆盖,在其中委托调用 SDK 的即可:
class HostZygotePreload : ZygotePreload {
private val duckDetector = DuckDetectorZygotePreload()
override fun doPreload(appInfo: ApplicationInfo) {
duckDetector.doPreload(appInfo) // 先执行 SDK 的 zygote 工作
// 再执行宿主自己的 app zygote 工作
}
}
实现见 DuckDetectorZygotePreload.kt,每一步都会以 DuckZygotePreload 标签打印 info 日志,便于排查。
钩子 2:早期启动捕获(透明 NativeActivity 启动器)
Mount 与 Virtualization 检测器会把扫描结果与第一个 Java Activity 之前采集的证据做对比。做法是把 SDK 自带的透明 NativeActivity 设为你的启动入口,并通过 meta-data 指定它捕获完证据后跳转的活动:
<activity
android:name="android.app.NativeActivity"
android:exported="true"
android:theme="@android:style/Theme.Translucent.NoTitleBar">
<meta-data android:name="android.app.lib_name" android:value="duckdetector" />
<meta-data
android:name="com.eltavine.duckdetector.launch_activity"
android:value="com.example.HomeActivity" />
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
随后在目标活动的 onCreate 与 onNewIntent 中调用 DuckDetector.captureLaunchEvidence(intent) 接收随 extras 传来的早期证据。参考 samples/sdk-consumer/src/main/AndroidManifest.xml 的完整接线。不接此钩子时,Mount 与 Virtualization 会把早期捕获报为不可用。
钩子 3:Mount 视图采样器(不可见 WebView)
隔离的 mount-view 扫描源自 PrivIsolated 的"先建 WebView 再绑定辅助进程"顺序。在 UI 启动前调用 DuckDetector.createProcMountSampler(activity),把返回的 1x1 透明 WebView 作为子视图挂上、并随 Activity 一起销毁即可。采样器的渲染进程以你包名的隔离服务运行,渲染进程退出时它会自动移除并销毁自身,避免 WebView 杀死宿主进程。
⚖️ 权限与用户同意:宿主说了算
SDK 不申请任何权限,以下权限由宿主按需声明,缺了只会让对应检测降级,不会崩溃:
| 权限 | 用于 | 缺少时的表现 |
|---|---|---|
QUERY_ALL_PACKAGES |
包清单(Custom ROM、Dangerous Apps、LSPosed 等) | 包可见性被过滤,清单中会记录未请求该权限 |
USE_BIOMETRIC / USE_FINGERPRINT |
TEE 的生物识别与 SOTER 环境检查 | 相关检查不可用 |
INTERNET / ACCESS_NETWORK_STATE |
TEE 在线刷新吊销列表、ADB 首包探测 | 相应网络矛盾不被评估 |
TEE 的在线吊销刷新还需要用户同意,SDK 不会自行弹窗:各检测器通过 consents 声明需要用户抉择的项,宿主用 decide(context, granted) 记录决定后再扫描一次。另外可用 DuckDetector.packageVisibility(context) 在读包相关结果前,先判断本进程看到的是完整、过滤还是不可读的包列表。
✅ 小结:接入清单
./gradlew :sdk:aar:publish构建 AAR(Nightly 包中也可直接取用);- 注册本地 Maven 仓库 +
implementation("com.eltavine.duckdetector:duckdetector-sdk:..."); DuckDetector.scan(context)并发扫描,按状态表解读结果;- 按需接入三个进程钩子:zygote preload(自动)、早期启动捕获、mount 视图采样器;
- 按检测需要声明权限,并向用户请求 TEE 吊销刷新的同意。
API 稳定性方面,稳定契约覆盖 :sdk:runtime、:core:detector、:core:report 与 :core:evidence 的公开 API,并在各模块 api/ 目录下有 ABI 转储受 CI 保护;单个检测器的专属类型(如 SuDetector)标注了 @DetectorSpecificApi,属于可能随版本变化的 opt-in API,接入时留意即可。更多细节请阅读 docs/guides/sdk-integration.md 与 docs/architecture/README.md。
