MuhammedErdemKazanci/device_trust

# 设备信任 [](https://pub.dev/packages/device_trust) [](LICENSE) [](https://github.com/MuhammedErdemKazanci/device_trust/actions/workflows/ci.yml) ## Flutter 的启发式设备完整性信号 对受损设备的轻量级检测：**root/越狱**、**模拟器/仿真器**、**hook/Frida** 以及 **调试器** 附加 —— 同时支持 **Android** 和 **iOS**。无需第三方 SDK。 | iOS | Android | | --- | ------- | |  |  | ## 功能 - ✅ **Android**: 使用 Kotlin + C++ (JNI) 收集原生信号 - ✅ **iOS**: 使用 Swift + Objective-C++ 执行原生安全检查 - ✅ **启发式方法**: 具有故障软化行为的多信号检测 - ✅ **极速**: 目标总执行时间为 1–20 毫秒（原生扫描通常为 1–5 毫秒） - ✅ **强类型 API**: 通过 MethodChannel 提供 `DeviceTrustReport` 模型 - ✅ **无第三方依赖**: 纯平台代码，无外部 SDK ## 支持的平台 | 平台 | 最低版本 | 备注 | | -------- | --------------- | ----- | | **Android** | API 24+ (Android 7.0) | Kotlin + C++ JNI | | **iOS** | iOS 13.0+ | Swift 5.0 | ## 快速开始 ### 安装 将以下内容添加到您的 `pubspec.yaml` 中： ``` dependencies: device_trust: ^3.0.0 ``` 运行： ``` flutter pub get ``` ### 基本用法 ``` import 'package:device_trust/device_trust.dart'; Future checkDeviceTrust() async { // Get the device trust report final report = await DeviceTrust.getReport(); // Simple policy: compromised if any major flag is true final compromised = report.rootedOrJailbroken || report.fridaSuspected || report.emulator || report.debuggerAttached; if (compromised) { print('⚠️ Device integrity compromised'); } else { print('✅ Device appears secure'); } // Log detailed signals print('Details: ${report.details}'); } ``` ### 特定平台检查 ``` final report = await DeviceTrust.getReport(); // Android-specific if (report.devModeEnabled) { print('Developer mode is enabled'); } if (report.adbEnabled) { print('ADB debugging is enabled'); } // iOS-specific: check jailbreak paths final jbPaths = report.details['jbPathHits'] as List? ?? []; if (jbPaths.isNotEmpty) { print('Jailbreak paths detected: $jbPaths'); } ``` ## API 参考 ### `DeviceTrust.getReport()` 返回一个包含以下字段的 `Future`： | 字段 | 类型 | 描述 | | ----- | ---- | ----------- | | `rootedOrJailbroken` | `bool` | 设备已 root (Android) 或已越狱 (iOS) | | `emulator` | `bool` | 正在模拟器/仿真器上运行 | | `fridaSuspected` | `bool` | 检测到 Frida 或 hook 框架 | | `debuggerAttached` | `bool` | 进程附加了调试器 | | `devModeEnabled` | `bool` | 已启用开发者模式（仅限 Android） | | `adbEnabled` | `bool` | 已启用 ADB 调试（仅限 Android） | | `details` | `Map` | 特定平台的信号和元数据 | ### `DeviceTrust.isSupported()` 返回 `Future`，指示当前平台是否受支持。 ## 平台说明 ### Android - **Manifest Queries**: 插件的 `AndroidManifest.xml` 声明了用于常见 root 管理应用（Magisk、SuperSU 等）和 Frida server 的 ``。这些会通过 Gradle 自动合并——无需手动配置。 - **原生库**: C++ 代码被编译为包含以下 ABI 的 AAR： - `arm64-v8a` (64位 ARM) - `armeabi-v7a` (32位 ARM) - `x86_64` (64位 x86) - **自动链接**: 由 CMake/ndk-build 处理链接；无需额外设置。 - **Gradle/Kotlin 兼容性**: 3.0.0+ 版本已针对 Android 的 内置 Kotlin 集成进行迁移，不再应用 Kotlin Gradle Plugin。 `device_trust` 不需要消费者端进行任何 Kotlin 配置。 - **16KB 页大小支持**: 支持 16KB 页大小的 Android 设备（部分设备上的 Android 15+）。所有 ABI 的原生库均使用 `-Wl,-z,max-page-size=16384` 构建。我们建议使用较新的 NDK (r26+) 以获得最佳兼容性。 ### iOS #### 依赖管理器支持 `device_trust` 同时支持 **CocoaPods** 和 **Swift Package Manager**，用于 iOS 原生 Flutter 插件集成。Flutter 应用开发者可以像添加和使用普通的 Dart/pub 依赖项一样使用 `device_trust` —— 无需手动进行原生 包配置。 - 此 Flutter 包的 **2.x 版本**要求所有消费者使用 **Flutter 3.41.0 或更高版本** 以及 **Dart ^3.11.0**，无论使用哪种 iOS 依赖管理器。 - **3.0.0+ 版本**要求 **Flutter 3.44.0 或更高版本**以及 **Dart ^3.12.0** 以实现 Android 内置 Kotlin 兼容性。使用较旧 Flutter 版本的项目 应继续使用 `device_trust: ^2.0.1`。 - **Swift Package Manager**: 通过以下命令启用 Flutter 的 SPM 集成： `flutter config --enable-swift-package-manager`，然后正常运行您的应用。 Flutter 会通过其原生 Swift 包目标自动解析 `device_trust`。 - **CocoaPods**: 仍完全支持 iOS 原生集成。基于 CocoaPods 的 消费者也必须满足上述最低 Flutter 和 Dart SDK 要求。 #### URL Schemes 为了进行越狱检测，插件会检查是否可以打开某些 URL schemes（`cydia://`、`sileo://` 等）。请将这些添加到您应用 `Info.plist` 的 `LSApplicationQueriesSchemes` 中： ``` LSApplicationQueriesSchemes cydia sileo zbra filza undecimus activator ``` **注意**：这仅用于 `canOpenURL` 检查——实际上并不会打开任何 URL。 - **Anti-Debug**: 原生函数 `DTNDenyDebuggerAttach()` 会调用 `ptrace(PT_DENY_ATTACH)`，但**仅**在以下情况生效： - **Release** 构建（非 Debug） - **物理设备**（非模拟器） 在 Debug/模拟器中，它是空操作，以免干扰开发。 - **桥接头文件 (Bridging Header)**: 不需要。CocoaPods 的 framework 模式会通过 umbrella header 暴露 C 函数，因此 Swift 代码可以自动识别它们。 ## 性能与故障软化行为 - **原生扫描持续时间**: 文件检查、进程检查和内存分析通常需要 1–5 毫秒。 - **总时间**: 目标端到端时间为 1–20 毫秒（原生 + Dart 开销）。 - **故障软化**: 如果原生库加载失败、超时或抛出错误，插件将返回安全的默认值（所有标志为 `false`，详情为空）。**应用不会崩溃。** ## 局限性与安全说明 ### 非 100% 检测 此插件使用**启发式检测**，可能会被以下方式绕过： - **Magisk Hide**、**Shamiko**（Android 上的 root 伪装） - **Frida 隐身模式**、**Objection**（hook 框架伪装） - 自定义 OS 修改或内核补丁 ### 多信号决策 - 插件**不会替您做出拦截决策**。 - 将多个信号结合使用以构建稳健的策略： final highRisk = report.rootedOrJailbroken && report.fridaSuspected; final mediumRisk = report.emulator || report.debuggerAttached; ### 误报 - **模拟器/仿真器**默认会被标记为已受损。在生产环境中，您可能需要允许它们用于内部测试。 - **Debug 模式**始终会附加调试器——这在开发过程中是正常的。 ## 示例应用 `example/` 目录包含一个生产级别的诊断 UI，显示： - 所有标志的**摘要**（颜色编码） - **策略评估**（示例） - **JSON 详情**（支持复制到剪贴板） - **检测到的信号**（路径、URL schemes、库） 运行它： ``` cd example flutter run -d ``` 有关特定平台的预期行为（例如，模拟器显示 `emulator: true`），请参见 [`example/README.md`](example/README.md)。 ## 常见问题 ### 为什么 iOS 没有桥接头文件？ 在 CocoaPods 下，framework 模式（`use_frameworks!`）会生成一个包含所有公共头文件的 umbrella header。在 Swift Package Manager 下，公共头文件通过包的 `include` 目录暴露。在这两种情况下，Swift 代码都能自动识别 C 函数（如 `DTNCollectNativeSignalsJSON`）——不需要手动添加桥接头文件。 ### 为什么我在某些设备上看不到 RWX 段？ - **iOS**: Apple 在现代设备上强制实施 **W^X**（Write XOR Execute）。RWX 段很少见，通常表明存在越狱或 Frida 注入。 - **模拟器**: 内存布局不同；RWX 信号可能不会按预期出现。 ### 这只适用于物理设备吗？ 不——它同时适用于**模拟器/仿真器**和**物理设备**。但是： - 模拟器会被标记为 `emulator: true`。 - 某些信号（如防调试 `ptrace`）仅在 Release 模式下的物理设备上激活。 ### 我可以自定义检测阈值吗？ 目前，阈值在原生层中是硬编码的。未来版本可能会公开配置选项（例如 RWX 段计数阈值）。 ## 路线图 - [ ] 添加更多信号（USB 调试状态、系统完整性检查） - [ ] 可配置的阈值（例如，调整 RWX 段敏感度） - [ ] 将可选的策略/示例 UI 作为单独的包提供 - [ ] 支持 Linux/Windows/macOS（欢迎社区贡献） ## 许可证 MIT 许可证。详情请参阅 [LICENSE](LICENSE)。 ## 支持 - **问题**: [GitHub Issues](https://github.com/MuhammedErdemKazanci/device_trust/issues) - **仓库**: [github.com/MuhammedErdemKazanci/device_trust](https://github.com/MuhammedErdemKazanci/device_trust) 用 ❤️ 为 Flutter 安全而构建

标签：Flutter, 环境检测, 移动开发, 设备完整性检测