目录

SafetyDetect

This module provides capabilities for assessing device environment security, including system integrity detection, malicious URL detection, unified risk control credential, and other security assessment features. You can leverage the detection results within their applications to evaluate device security risks and implement appropriate protective measures.

Since: 5.0.0(12)

Modules to Import

import { safetyDetect } from '@kit.DeviceSecurityKit';

SysIntegrityRequest

Request parameter for system integrity check.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
nonce string No No A randomly generated nonce value passed by your app, which is used to prevent replay attacks. Each request must be unique, and this value will be included in the detection result. A nonce value must contain 16 to 66 bytes and be encoded using Base64.

SysIntegrityResponse

Return value of system integrity check.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
result string No No System integrity check result in JWS format. For details about the JWS content, see Development Procedure in System Integrity Check.

UrlCheckRequest

Request parameter for URL check.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
urls Array<string> No No List of URLs to be checked. A maximum of 10 URLs can be passed in, and the length of each URL cannot exceed 4096 bytes.

UrlCheckResponse

Return value of URL check.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
results Array<UrlCheckResult> No No URL check result. Each result contains the checked URL and its threat type.

UrlCheckResult

URL check result details.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Type Read-Only Optional Description
url string No No Corresponds to the URL to be checked in the request parameter.
threat UrlThreatType No No URL threat type.

UrlThreatType

Enumerates URL threat types.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Name Value Description
NORMAL 0 No threat detected.
MALWARE 1 Malicious URL.
PHISHING 2 Phishing URL.
OTHERS 3 Other URL threats.

safetyDetect.checkSysIntegrity

checkSysIntegrity(req: SysIntegrityRequest): Promise<SysIntegrityResponse>

Obtains the online system integrity check result of the current device. This API uses a promise to return the result.

This API involves device-cloud synergy and time-consuming operations such as network connection. Therefore, do not execute this API in the UI thread, in order to avoid UI thread blocking.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
req SysIntegrityRequest Yes

Request parameter, including the nonce value.

A nonce value must contain 16 to 66 bytes and be encoded using Base64.

Returns:

Type Description
Promise<SysIntegrityResponse> Promise used to return the system integrity check result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401

Invalid parameters.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
801

API is not supported.

Applicable versions: 5.1.0(18)+
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800005

The number of calls exceeds the parallel threshold.

Applicable versions: 5.1.0(18)+
1010800006

The invoking frequency exceeds the threshold.

Applicable versions: 5.1.0(18)+
1010800007

Operation timeout.

Applicable versions: 5.1.0(18)+
1010800008

The cloud service traffic exceeds the threshold.

Applicable versions: 5.1.0(18)+

Example:

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'SafetyDetectJsTest';

// Request system integrity check and process the result.
let req : safetyDetect.SysIntegrityRequest = {
  nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // Random nonce value generated by the server.
};
try {
  hilog.info(0x0000, TAG, 'CheckSysIntegrity begin.');
  const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrity(req);
  hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrity: %{public}s', data.result);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'CheckSysIntegrity failed: %{public}d %{public}s', e.code, e.message);
}

safetyDetect.checkUrlThreat

checkUrlThreat(req: UrlCheckRequest): Promise<UrlCheckResponse>

Checks whether a URL is malicious. This API uses a promise to return the result.

This API involves device-cloud synergy and time-consuming operations such as network connection. Therefore, do not execute this API in the UI thread, in order to avoid UI thread blocking.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
req UrlCheckRequest Yes

Request parameter, including the list of URLs to be checked.

A maximum of 10 URLs can be passed in, and the length of each URL cannot exceed 4096 bytes.

Returns:

Type Description
Promise<UrlCheckResponse> Promise used to return the URL check result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401

Invalid parameters.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
801

API is not supported.

Applicable versions: 5.1.0(18)+
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800005

The number of calls exceeds the parallel threshold.

Applicable versions: 5.1.0(18)+
1010800006

The invoking frequency exceeds the threshold.

Applicable versions: 5.1.0(18)+
1010800007

Operation timeout.

Applicable versions: 5.1.0(18)+
1010800008

The cloud service traffic exceeds the threshold.

Applicable versions: 5.1.0(18)+

Example:

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'SafetyDetectJsTest';

// Request URL check and process the result.
let req : safetyDetect.UrlCheckRequest = {
  urls : ['https://test1.com']
};
try {
  hilog.info(0x0000, TAG, 'CheckUrlThreat begin.');
  const data: safetyDetect.UrlCheckResponse = await safetyDetect.checkUrlThreat(req);
  hilog.info(0x0000, TAG, 'Succeeded in checkUrlThreat: %{public}s %{public}d', data.results[0].url, data.results[0].threat);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'CheckUrlThreat failed: %{public}d %{public}s', e.code, e.message);
}

safetyDetect.checkSysIntegrityOnLocal

checkSysIntegrityOnLocal(): Promise<string>

Obtains the local system integrity check result of the current device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.1.0(18).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 5.1.0(18)

Returns:

Type Description
Promise<string> Promise used to return the local system integrity detection result in JSON format. For details about the JSON structure, see the JSON structure of the local system integrity detection result.

JSON structure of the local system integrity detection result:

Field Type Description
basicIntegrity boolean Local system integrity check result. The value true indicates that the check result is intact, and the value false indicates that risks exist.
detail Array<string> This field is optional. When the value of basicIntegrity is false, this field provides the reason why risks exist. For details about the value, please refer to the value description of the detail field.

Value description of the detail field:

Value Description
jailbreak The device is jailbroken.
emulator The device is a non-real device.
attack The device is attacked.
unlock The device is unlocked.

Example (return value):

{
  "basicIntegrity": false,
  "detail": [
    "attack",
    "jailbreak",
    "emulator"
  ]
}

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
801 API is not supported.
1010800001 Internal error.
1010800004 Verify capability fail.
1010800005 The number of calls exceeds the parallel threshold.
1010800006 The invoking frequency exceeds the threshold.
1010800007 Operation timeout.

Example:

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'SafetyDetectJsTest';

// Request local system integrity check and process the result.
try {
  hilog.info(0x0000, TAG, 'CheckSysIntegrityOnLocal begin.');
  const result: string = await safetyDetect.checkSysIntegrityOnLocal();
  hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityOnLocal: %{public}s', result);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'CheckSysIntegrityOnLocal failed: %{public}d %{public}s', e.code, e.message);
}

safetyDetect.checkSysIntegrityEnhanced

checkSysIntegrityEnhanced(req: SysIntegrityRequest): Promise<SysIntegrityResponse>

Obtains the enhanced online system integrity check result of the current device. This API uses a promise to return the result.

This API involves device-cloud synergy and time-consuming operations such as network connection. Therefore, do not execute this API in the UI thread, in order to avoid UI thread blocking.

Atomic service API: This API can be used in atomic services since API version 6.0.0(20).

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
req SysIntegrityRequest Yes

Request parameter, including the nonce value.

A nonce value must contain 16 to 66 bytes and be encoded using Base64.

Returns:

Type Description
Promise<SysIntegrityResponse> Promise used to return the enhanced system integrity check result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
801 API is not supported.
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800004 Verify capability fail.
1010800005 The number of calls exceeds the parallel threshold.
1010800006 The invoking frequency exceeds the threshold.
1010800007 Operation timeout.
1010800008 The cloud service traffic exceeds the threshold.

Example:

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'SafetyDetectJsTest';

// Request enhanced system integrity check and process the result.
let req : safetyDetect.SysIntegrityRequest = {
  nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // Random nonce value generated by the server.
};
try {
  hilog.info(0x0000, TAG, 'CheckSysIntegrityEnhanced begin.');
  const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrityEnhanced(req);
  hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityEnhanced: %{public}s', data.result);
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'CheckSysIntegrityEnhanced failed: %{public}d %{public}s', e.code, e.message);
}

RiskFactorType

Enumerates risk factor types.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Device behavior differences: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.

Since: 26.0.0

Name Value Description
HDC_DEBUG_STATE "hdcDebugState" HDC debugging.
IS_DEVELOPER_MODE "isDeveloperMode" Developer mode.
IS_VPN_STATUS "isVpnStatus" VPN.
IS_NET_PROXY_STATUS "isNetProxyStatus" Network proxy.
SIM_CNT "simCnt" Number of inserted SIM cards.
OOBE_CNT "oobeCnt" Number of OOBE operations.
ODID_RESET_CNT "odidResetCnt" Number of ODID reset times.
ODID "odid" Current ODID value.
IS_DISPLAY_CAPTURED "isDisplayCaptured" Screen recording.
GLOBAL_WINDOW_STATE "globalWindowState" Foreground window mode.
BATTERY_CHARGE_STATE "batteryChargeState" Battery charging.
BATTERY_HEALTH_STATE "batteryHealthState" Battery health.
ON_CALL_STATE "onCallState" On call.

RiskFactorRequest

Risk factor query parameter.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Device behavior differences: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.

Since: 26.0.0

Name Type Read-Only Optional Description
nonce string No No A randomly generated nonce value passed by your app, which is used to prevent replay attacks. Each request must be unique, and this value will be included in the detection result. A nonce value must contain 16 to 66 bytes and be encoded using Base64.
queries Array<FactorQuery> No No List of risk factors to query. The list can contain a maximum of 20 items and cannot be empty.

FactorQuery

Risk factor query item.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Device behavior differences: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.

Since: 26.0.0

Name Type Read-Only Optional Description
factor RiskFactorType No No Risk factor type to query.

RiskFactorResponse

Return value for risk factor query.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Device behavior differences: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.

Since: 26.0.0

Name Type Read-Only Optional Description
result string No No Risk factor query result in JWS format. For details about the JWS content, see Development Procedure in Unified Risk Control.

safetyDetect.queryRiskFactors

queryRiskFactors(req: RiskFactorRequest): Promise<RiskFactorResponse>

Queries system-level risk factor data. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Security.SafetyDetect

Model restriction: This API can be used only in the stage model.

Device behavior differences: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.

Since: 26.0.0

Parameters:

Name Type Mandatory Description
req RiskFactorRequest Yes Risk factor query parameter.

Returns:

Type Description
Promise<RiskFactorResponse> Promise used to return the risk factor result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
801 API is not supported.
1010800004 Verify capability fail.
1010800005 The number of calls exceeds the parallel threshold.
1010800006 The invoking frequency exceeds the threshold.
1010800007 Operation timeout.
1010800011 Failed to query the risk factor.

Example:

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'SafetyDetectJsTest';

// Request risk control factor data and process the result.
const request: safetyDetect.RiskFactorRequest = {
 nonce: 'a1b2c3d4e5f6g7hfsdfxvsdae8', // Anti-replay nonce of 16 to 66 bytes.
 queries: [
     { factor: safetyDetect.RiskFactorType.HDC_DEBUG_STATE },
     { factor: safetyDetect.RiskFactorType.IS_DEVELOPER_MODE },
     { factor: safetyDetect.RiskFactorType.ODID_RESET_CNT }
 ]
};
try {
 hilog.info(0x0000, TAG, 'QueryRiskFactors begin.');
 const response: safetyDetect.RiskFactorResponse = await safetyDetect.queryRiskFactors(request);
 hilog.info(0x0000, TAG, 'Succeeded in QueryRiskFactors: %{public}s', response.result);
} catch (err) {
 let e: BusinessError = err as BusinessError;
 hilog.error(0x0000, TAG, 'QueryRiskFactors failed: %{public}d %{public}s', e.code, e.message);
}