【HarmonyOS 5】鸿蒙检测系统完整性

一、前言

从现实安全威胁来看，设备系统完整性风险已影响至移动应用的各个场景。不少用户因使用越狱设备（Jailbreak）或非真实设备（Emulator），导致应用安全防护机制失效——某金融类APP曾发现用户在越狱设备上绕过安全校验，非法获取账户资金操作权限，直接引发数千万资金损失风险，此类事件不仅导致用户资产暴露于黑客攻击之下，更严重损害企业金融风控体系的公信力。

与此同时，非真实设备（Emulator）常被黑产用于模拟用户环境实施批量攻击：恶意团伙通过模拟器批量注册虚假账号，利用自动化工具绕过设备指纹校验，在电商平台薅取数百万补贴资金；或通过篡改模拟器参数，伪造地理位置信息实施精准诈骗，导致企业反欺诈系统形同虚设，直接引发业务信任危机。

而设备被攻击（Attack）的场景更凸显系统完整性防护的紧迫性：黑客通过植入root提权工具突破设备底层防护，在用户无感知的情况下窃取支付凭证、生物特征等敏感数据——某社交APP用户因设备被植入恶意程序，通讯录信息及聊天记录遭批量窃取并贩卖，不仅导致个人隐私泄露，更引发连锁的电信诈骗案件；部分企业因未有效拦截被攻击设备的接入，导致内部测试环境遭渗透，核心代码与业务逻辑被窃取，直接面临高达数亿的经济损失与品牌声誉的断崖式崩塌。

应用通过华为 HarmonyOS 的Device Security Kit提供的safetyDetect.checkSysIntegrity 接口，可检测系统环境是否完整，是否为模拟器，被破解设备，越狱设备，并根据检测结果提示或拦截用户访问。

二、业务流程与使用

1.首先需要在AGC平台给对应项目应用，进行安全检测服务的开通：

登录AppGallery Connect( https://developer.huawei.com/consumer/cn/service/josp/agc/index.html#/ )网站，选择“我的项目”。在项目列表中找到需要开通Device Security服务的项目。
在这里插入图片描述

在这里插入图片描述
之后重新生成调试Profile，在项目中手动进行签名证书的配置，就可使用该接口了。否则会try catch提示Permission Denied。

2.创建safetyDetect.SysIntegrityRequest配置需要检测的Url数组，调用safetyDetect.checkSysIntegrity接口异步请求检测：
在这里插入图片描述

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@ohos.base';
import { hilog } from '@kit.PerformanceAnalysisKit';const req = { nonce: '服务器生成的随机值' };
try {const data = await safetyDetect.checkSysIntegrity(req);console.log('检测结果：', data.result); // true/false
} catch (err) {console.error('错误码：', err.code, '信息：', err.message);
}

3.注意事项：
（1）每日每设备调用次数，最多1 万次。
（2）每分钟调用次数，最多5 次。
（3）并发调用数，最多5 个。

三、源码示例：

在这里插入图片描述

// 导入所需模块
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { promptAction } from '@kit.ArkUI';@Entry
@Component
struct deviceCheckTestPage {private TAG: string = "DeviceCheckTestPage";// 存储检测结果@State resultMsg: string = '未检测';@State detailMsg: string = '';// 生成随机nonce（示例方法，实际需从服务器获取）private generateNonce(): string {// 示例中使用本地随机生成（仅用于演示）// 实际开发必须从应用服务器动态获取，确保每次请求唯一性return 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // 从服务器生成的随机的nonce值}// 系统完整性检测函数private async checkSystemIntegrity() {try {console.info(this.TAG, '开始检测系统完整性')// 获取nonce（示例：本地生成，实际需从服务器获取）const nonce = this.generateNonce();// 构建检测请求const req: safetyDetect.SysIntegrityRequest = {nonce: nonce};// 调用检测接口const response = await safetyDetect.checkSysIntegrity(req);console.info(this.TAG, '检测结果：%{public}s', response.result)// 处理结果this.processResult(response);} catch (error) {const err = error as BusinessError;console.info(this.TAG, '检测结果：%{public}s', '检测失败：%{public}d %{public}s', err.code, err.message)this.showPrompt('检测失败' + `错误码：${err.code}\n${err.message}`);}}// 结果处理函数private processResult(response: safetyDetect.SysIntegrityResponse) {// SysIntegrityResponse - result// nonce：调用checkSysIntegrity接口时传入的nonce字符串。//// timestamp：服务器生成的时间戳。//// hapBundleName：您应用的包名。//// hapCertificateSha256：您应用的签名证书SHA256摘要。//// basicIntegrity：系统完整性检测的结果，true表示检测结果完整，false表示存在风险。//// appId：您应用的appid。//// detail：可选字段，当basicIntegrity结果为false时，该字段将提供存在风险的原因，// JWS格式的系统完整性检测结果。JWS内容详见《Device Security Kit开发指南》中的系统完整性检测开发步骤。let result = response.result;// jailbreak：设备被越狱。// emulator：非真实设备。// attack：设备被攻击。this.resultMsg = `系统完整性：${response ? '安全' : '风险'}`;if (!result) {// this.detailMsg = `风险原因：${detail.join('、')}`;} else {this.detailMsg = '无具体风险信息';}this.showPrompt('检测完成' + `${this.resultMsg}\n${this.detailMsg}`);}// 提示框函数private showPrompt(message: string) {promptAction.showToast({message: message})}build() {Column() {Text('系统完整性检测Demo').fontSize(20).fontWeight(500).margin(10);Button('开始检测').width('90%').height(48).backgroundColor('#007DFF').fontColor('white').onClick(() => this.checkSystemIntegrity()).margin(20);Text(this.resultMsg).fontSize(16).fontWeight(400).margin({ bottom: 5 });Text(this.detailMsg).fontSize(14).fontColor('#666')}.padding(20).width('100%').height('100%').justifyContent(FlexAlign.Center).backgroundColor('#F5F5F5');}
}