【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接口异步请求检测：
dart
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 个。
三、源码示例：
dart
// 导入所需模块
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');
}
}系统完整性检测结果签名验证的java示例代码，仅供应用服务器参考。（https://gitee.com/harmonyos_samples/device-security-kit-samplecode-safetydetect-serverdemo-java）