Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Device Security Situational Awareness/ Device Obtaining Comprehensive Security Situational Awareness Configurations
Updated on 2025-07-01 GMT+08:00

Device Obtaining Comprehensive Security Situational Awareness Configurations

Topics

Upstream: $oc/devices/{device_id}/sys/shadow/get/request_id={request_id}

Downstream: $oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}

Upstream Request Parameters

Parameter

Mandatory

Type

Description

object_device_id

No

String

Explanation:

ID of the device that requests its device shadow.

service_id

Yes

String

Explanation:

ID of a service of the device that requests the device shadow. The value is fixed at $security_detection_config for security situational awareness.

Downstream Response Parameters

Parameter

Mandatory

Type

Description

object_device_id

Yes

String

Explanation:

ID of the device that requests its device shadow.

shadow

No

List<ShadowData>

Explanation:

Shadow data.

ShadowData structure

Parameter

Mandatory

Type

Description

service_id

Yes

String

Explanation:

The value is fixed at $security_detection_config for security check.

desired

No

PropertiesData

Explanation:

Property list of security check configuration.

reported

No

PropertiesData

Explanation:

Property list in the reported section of the device shadow.

version

No

Integer

Explanation:

Device shadow version.

PropertiesData structure

Parameter

Mandatory

Type

Description

properties

Yes

SecurityProperties

Explanation:

Security situational awareness configuration details.

event_time

No

String

Explanation:

UTC time of the device property data. The format is yyyyMMdd'T'HHmmss'Z', for example, 20161219T114920Z.

SecurityProperties Structure

Parameter

Mandatory

Type

Description

memoryCheck

No

Integer

Explanation:

Memory check status. Options: 0 (disabled) and 1 (enabled).

Value range:

0 to 1

memoryThreshold

No

Integer

Explanation:

Memory usage alarm threshold.

Value range:

1 to 100

memoryCheckReportPeriod

No

Integer

Explanation:

Memory check reporting period, in hours.

Value range:

1 to 24

portCheck

No

Integer

Explanation:

Port check status. Options: 0 (disabled) and 1 (enabled).

Value range:

0 to 1

portCheckReportPeriod

No

Integer

Explanation:

Port check report period. Range: 1 to 24, in hours.

Value range:

1 to 24

cpuUsageCheck

No

Integer

Explanation:

CPU check status. Options: 0 (disable) and 1 (enable).

Value range:

0 to 1

cpuUsageThreshold

No

Integer

Explanation:

CPU usage alarm threshold. Range: 1 to 100.

Value range:

1 to 100

cpuUsageCheckReportPeriod

No

Integer

Explanation:

CPU check reporting period. Range: 1 to 24, in hours.

Value range:

1 to 24

diskSpaceCheck

No

Integer

Explanation:

Disk check status. Options: 0 (disable) and 1 (enable).

Value range:

0 to 1

diskSpaceThreshold

No

Integer

Explanation:

Disk usage alarm threshold. Range: 1 to 100.

Value range:

1 to 100

diskSpaceCheckReportPeriod

No

Integer

Explanation:

Disk check reporting period. Range: 1 to 24, in hours.

Value range:

1 to 24

batteryPercentageCheck

No

Integer

Explanation:

Battery check status. Options: 0 (disable) and 1 (enable).

Value range:

0 to 1

batteryPercentageThreshold

No

Integer

Explanation:

Battery usage alarm threshold. Range: 1 to 100.

Value range:

1 to 100

batteryPercentageCheckReportPeriod

No

Integer

Explanation:

Battery check reporting period. Range: 1 to 24, in hours.

Value range:

1 to 24

loginLocalCheck

No

Integer

Explanation:

Local login check status. Options: 0 (disable) and 1 (enable).

Value range:

0 to 1

loginBruteForceCheck

No

Integer

Explanation:

Brute-force login check status. Options: 0 (disable) and 1 (enable).

Value range:

0 to 1

maliciousIPCheck

No

Integer

Explanation:

Malicious IP address check status. Options: 0 (disabled) and 1 (enabled).

Value range:

0 to 1

fileTamperCheck

No

Integer

Explanation:

File tampering check status. Options: 0 (disabled) and 1 (enabled).

Value range:

0 to 1

Example Upstream Request

Topic: $oc/devices/{device_id}/sys/shadow/get/request_id={request_id} 
Data format:
{
	"object_device_id": "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
	"service_id": "$security_detection_config"
}

Example Downstream Response

Topic: $oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}
Data format:
{
  "object_device_id": "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
  "shadow": [
    {
      "service_id": "$security_detection_config",
      "desired": {
        "properties": {
        "loginBruteForceCheck": 1,
        "cpuUsageCheck": 1,
        "cpuUsageThreshold": 80,
        "cpuUsageCheckPeriod": 2,
        "memoryCheck": 1,
        "memoryThreshold": 80,
        "memoryCheckReportPeriod": 24,
        "batteryPercentageCheck": 1,
        "batteryPercentageReportPeriod": 24,
        "batteryPercentageThreshold": 20
        },
        "event_time": "20151212T121212Z"
      },
      "reported": {
        "properties": null,
        "event_time": null
      },
      "version": 1
    }
  ]
}