@zero-bits/react-native-talsec

Talsec freeRASP 安全 SDK 的 React Native 原生封装（Native Module）。支持 Android & iOS 双端，通过 JS 层动态配置，无需修改原生代码。

功能

• 🔒 越狱 / Root 检测
• 🔒 调试器接入检测
• 🔒 应用签名篡改检测
• 🔒 模拟器运行检测
• 🔒 Runtime Hook 注入检测
• 🔒 设备绑定 / 指纹异常检测
• 🔒 系统 VPN 代理检测
• 🔒 系统时间篡改检测
• 🔒 恶意软件检测（Android）
• 🔒 代码混淆验证（Android）
• 🔒 截图 / 录屏检测（iOS）
• 🔒 安全芯片异常检测（iOS）

安装

npm install @zero-bits/react-native-talsec
# iOS 需额外执行
cd ios && pod install

Android 配置

无需修改任何原生代码。将 TalsecPackage 注册到 MainApplication.java 的 getPackages() 中：

packages.add(new TalsecPackage());

iOS 配置

1. 将 TalsecRuntime.xcframework 放入本包的 ios/ 目录（已内置）。
2. 在 Xcode 中将 TalsecRuntime.xcframework 的嵌入模式设为 Embed & Sign。
3. 无需修改 AppDelegate。

用法

import { startTalsec, addThreatListener } from '@zero-bits/react-native-talsec';

useEffect(() => {
  // 1. ⚠️ 必须先注册监听器（防止事件竞争丢失）
  const sub = addThreatListener((threatType) => {
    // 开发时放行调试器
    if (__DEV__ && threatType === 'debug') return;
    // 网页下载安装放行
    if (threatType === 'untrustedInstallationSource') return;
    
    Alert.alert('安全警告', `检测到威胁：${threatType}`);
  });

  // 2. 然后再初始化 Talsec
  startTalsec({
    androidConfig: {
      packageName: 'com.example.app',
      certificateHashes: ['YOUR_BASE64_SHA256_HASH'],
    },
    iosConfig: {
      appBundleIds: ['com.example.app'],
      appTeamId: 'YOUR_10_CHAR_TEAM_ID',
    },
    watcherMail: '[email protected]',
    isProd: !__DEV__,
  }).catch((err) => {
    console.error('Talsec 启动失败', err);
  });

  return () => sub?.remove();
}, []);

威胁类型说明

| threatType | 平台 | 说明 | |---|---|---| | appIntegrity | Android / iOS | 应用签名被篡改或二次打包 | | privilegedAccess | Android / iOS | Root / 越狱 | | debug | Android / iOS | 调试器接入 | | hooks | Android / iOS | Runtime 注入 / Hook | | emulator | Android / iOS | 模拟器环境 | | untrustedInstallationSource | Android / iOS | 非官方渠道安装 | | deviceBinding | Android / iOS | 设备指纹被克隆或绑定异常 | | deviceID | Android / iOS | 设备 ID 变更或异常 | | systemVPN | Android / iOS | 检测到系统级 VPN 代理 | | timeSpoofing | Android / iOS | 系统时间被篡改 | | obfuscationIssues | Android | 代码未混淆（Release 包必须启用混淆） | | malware | Android | 恶意软件（详情见 Logcat: TalsecThreatListener） | | passcode | iOS | 设备未设置锁屏密码 | | missingSecureEnclave | iOS | 安全芯片（Secure Enclave）异常 | | screenshot | iOS | 系统截图事件 | | screenRecording | iOS | 系统录屏事件 |

获取 Android 签名哈希

keytool -exportcert -alias YOUR_ALIAS -keystore YOUR_KEYSTORE \
  -storepass YOUR_PASSWORD | openssl dgst -sha256 -binary | openssl base64

常见问题 (Troubleshooting)

必须配置 Jetifier 黑名单（非常重要！）

由于 Talsec SDK 内部包含极强的防篡改和混淆机制，如果 Android 的 Jetifier 工具尝试去修改它的字节码，会直接触发安全警报（appIntegrity 篡改）导致 App 闪退。

您必须在主项目的 android/gradle.properties 文件中添加以下配置：

android.jetifier.blacklist=TalsecSecurity-Community,com.aheaditec.talsec.security,com.aheaditec.talsec.security:TalsecSecurity-Community,talsec

Android 编译报 startup-runtime 或 localbroadcastmanager 等依赖冲突怎么办？

如果在集成后，Android 编译时报错提示找到多个不同版本的 startup-runtime 或 localbroadcastmanager，请在您的主项目（宿主 App）的 android/app/build.gradle 顶部加入以下代码，强制统一版本：

configurations.all {
    resolutionStrategy {
        force "androidx.startup:startup-runtime:1.0.0"
        force "androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"
    }
}

注意：切勿将 resolutionStrategy 或 gradle.properties 配置写在本 npm 包中，否则作用域会被宿主覆盖而失效。解决依赖冲突和全局配置的逻辑必须留在主项目中。

iOS appIntegrity 在开发阶段总是触发？

这是预期行为。当使用 Xcode 以 Debug 模式安装 App 时，苹果使用的是本地开发证书，而非您配置的 appTeamId 官方证书，因此会触发签名校验失败。

解决方案：确保 isProd: !__DEV__，在开发模式下 Talsec 会自动放宽签名校验。