AWS IoT
Developer Guide

Detect

AWS IoT Device Defender Detect allows you to identify unusual behavior that may indicate a compromised device by monitoring the behavior of your devices. Using a combination of cloud-side metrics (from AWS IoT) and device-side metrics (from agents you install on your devices) you can detect changes in connection patterns, devices that communicate to unauthorized or unrecognized endpoints, and changes in inbound and outbound device traffic patterns. You create security profiles, which contain definitions of expected device behaviors, and assign them to a group of devices or to all the devices in your fleet. AWS IoT Device Defender Detect uses these security profiles to detect anomalies and send alerts via AWS CloudWatch metrics and AWS SNS notifications.

AWS IoT Device Defender Detect is capable of detecting a variety of security issues frequently found in connected devices:

  • Traffic from a device to a known malicious IP address or to an unauthorized endpoint that indicates a potential malicious command and control channel.

  • Anomalous traffic, such as a spike in outbound traffic, that indicates a device is participating in a DDoS.

  • Devices with remote management interfaces and ports that are remotely accessible.

  • A spike in the rate of messages sent to your account— so that a rogue device does not end up costing you in per-message charges.

Use cases:

Measure attack surface

You can use AWS IoT Device Defender Detect to measure the attack surface of your devices. For example, you can identify devices with service ports which are often the target of attack campaigns (telnet service running on ports 23/2323, SSH service running on port 22, HTTP/S services running on ports 80/443/8080/8081). While these service ports might have legitimate reasons to be used on the devices, they are also usually part of the attack surface for adversaries and carry associated risks. After Detect alerts you to the attack surface, you can either decide to minimize it (by eliminating unused network services) or run additional assessments to identify security weaknesses (for example, telnet configured with common, default or weak passwords).

Detect device behavioral anomalies with possible security root causes

You can use AWS IoT Device Defender Detect to alert you to unexpected device behavioral metrics (the number of open ports, number of connections, an unexpected open port, connections to unexpected IP addresses) which might indicate a security breach. For example, a higher than expected number of TCP connections may indicate a device is being used for a DDoS attack. A process listening on a port other than the one you expect may indicate a backdoor installed on a device for remote control. You can use Detect to probe the health of your device fleets and verify your security assumptions (for example, no device is listening on port 23 or 2323).

Detect a mis-configured device

A spike in the number or size of messages sent from a device to your account might indicate a mis-configured device. Such a device could increase your per-message charges. Similarly, a device with many authorization failures could require a re-configured policy.

Concepts

metric

AWS IoT Device Defender Detect uses metrics to detect anomalous behavior. Detect compares the reported value of a metric with the expected value you provide. These metrics can be taken from two sources: (a) cloud-side metrics, and (b) device-side metrics:

(a) Abnormal behavior on the AWS IoT network is detected by using cloud-side metrics such as the number of authorization failures, or the number or size of messages a device sends or receives via AWS IoT.

(b) AWS IoT Device Defender Detect can also collect, aggregate, and monitor metrics data generated by AWS IoT devices, for example, the ports a device is listening on, the number of bytes or packets sent, or the device's TCP connections.

You can use AWS IoT Device Defender Detect with cloud-side metrics alone. To use device-side metrics you must first deploy an agent on your AWS IoT connected devices or device gateways to collect the metrics and send them to AWS IoT. See Sending Metrics from Devices

security profile

A security profile defines anomalous behaviors for a group of devices (a thing group) or for all devices in your account, and specifies what actions to take when an anomaly is detected. You can create a security profile and associate it with a group of devices using the console or with AWS IoT API commands. AWS IoT Device Defender Detect starts recording security-related data and uses the behaviors defined in the security profile to detect anomalies in the behavior of the devices.

behavior

A behavior tells AWS IoT Device Defender Detect how to recognize when a device is doing something abnormal. Each behavior consists of a name, a metric, an operator, and a value or a statistical threshold. For some metrics, a time period (durationSeconds) is also required. Any device action that does not match a defined behavior statement triggers an alert.

alert

When an anomaly is detected, an alert notification can be sent via a CloudWatch metric (see AWS IoT Metrics) or an SNS notification. An alert notification is also displayed in the AWS IoT CDM console along with additional information about the alert, and a history of alerts for the device. An alert is also sent when a monitored device stops exhibiting anomalous behavior or when it had been causing an alert but stops reporting for an extended period.

Behaviors

A security profile contains a set of behaviors. Each behavior contains a metric that specifies the normal behavior for a group of devices or for all devices in your account (see Metrics and CreateSecurityProfile).

The following describes some of the fields that are used in the definition of a behavior:

name

The name you wish to give to the behavior.

metric

The name of the metric used. That is, what is measured by the behavior.

criteria

The criteria that determine if a device is behaving normally in regard to the metric.

comparisonOperator

The operator that relates the thing measured (metric) to the criteria (value or statisticalThreshold).

Possible values are: "less-than", "less-than-equals", "greater-than", "greater-than-equals", "in-cidr-set", "not-in-cidr-set", "in-port-set", and "not-in-port-set". Not all operators are valid for every metric-- operators for CIDR sets and ports are only for use with metrics involving such entities.

value

The value to be compared with the metric. Depending on the type of metric, this should contain a count (a value), cidrs (a list of CIDRs) or ports (a list of ports).

statisticalThreshold

The statistical threshold by which a behavior violation is determined. This field contains a statistic field which has the following possible values: "p0", "p0.1", "p0.01", "p1", "p10", "p50", "p90", "p99", "p99.9", "p99.99", or "p100".

This statistic indicates a percentile. It resolves to a value by which compliance with the behavior is determined. Metrics are collected one or more times over the specified duration (durationSeconds) from all reporting devices associated with this security profile, and percentiles are calculated based on that data. After that, measurements are collected for a device and accumulated over the same duration. If the resulting value for the device falls above or below (comparisonOperator) the value associated with the percentile specified, then the device is considered to be in compliance with the behavior, otherwise it is in violation of the behavior.

A percentile indicates the percentage of all the measurements considered which fall below the associated value. For example, if the value associated with "p90" (the 90th percentile) is 123, then 90% of all measurements were below 123.

durationSeconds

Use this to specify the period of time over which the behavior is evaluated, for those criteria which have a time dimension (for example, NUM_MESSAGES_SENT). For a statisticalThreshhold metric comparison, this is the time period during which measurements are collected for all devices to determine the statisticalThreshold values, and then for each device to determine how its behavior ranks in comparison.

consecutiveDatapointsToAlarm

If a device is in violation of the behavior for the specified number of consecutive datapoints, an alarm occurs. If not specified, the default is 1. (Note that this differs from the IoT console where a value of 3 is presented by default, but can be overridden.)

consecutiveDatapointsToClear

If an alert has occurred and the offending device is no longer in violation of the behavior for the specified number of consecutive datapoints, the alarm is cleared. If not specified, the default is 1. (Note that this differs from the IoT console where a value of 3 is presented by default, but can be overridden.)

Metrics

aws:message-byte-sizemore info (1)
aws:message-byte-size

The number of bytes in a message.

more info (1)

Use this metric to specify the maximum or minimum size (in bytes) of each message transmitted from a device to AWS IoT.

Source: cloud-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: bytes

Example:

{ "name": "Max Message Size", "metric": "aws:message-byte-size", "criteria": { "comparisonOperator": "less-than", "value": { "count": 1024 }, "consecutiveDatapointsToAlarm": 3, "consecutiveDatapointsToClear": 3 } }

Example using a statisticalThreshold:

{ "name": "Large Message Size", "metric": "aws:message-byte-size", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 3, "consecutiveDatapointsToClear": 3 } }

An alarm occurs for a device if, during three consecutive 5 minute periods, it transmits messages whose cumulative size is more than that measured for 90 percent of all other devices reporting for this security profile behavior.

 

aws:num-messages-received / aws:num-messages-sentmore info (2)
aws:num-messages-received / aws:num-messages-sent

The number of messages received or sent by a device during a given time period.

more info (2)

Use this metric to specify the maximum or minimum number of messages that may be sent or received between AWS IoT and each device in a given period of time.

Source: cloud-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: messages

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "Out bound message count", "metric": "aws:num-messages-sent", "criteria": { "comparisonOperator": "less-than", "value": { "count": 50 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 2 } }

Example using a statisticalThreshold:

{ "name": "Out bound message rate", "metric": "aws:num-messages-sent", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p99" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 2 } }

 

aws:all-bytes-outmore info (3)
aws:all-bytes-out

The number of outbound bytes from a device during a given time period.

more info (3)

Use this metric to specify the maximum or minimum amount of out-bound traffic that a device should send, measured in bytes in a given period of time.

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: bytes

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "TCP outbound traffic", "metric": "aws:all-bytes-out", "criteria": { "comparisonOperator": "less-than", "value": { "count": 4096 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 5, "consecutiveDatapointsToClear": 4 } }

Example using a statisticalThreshold:

{ "name": "TCP outbound traffic", "metric": "aws:all-bytes-out", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p50" }, "durationSeconds": 900, "consecutiveDatapointsToAlarm": 5, "consecutiveDatapointsToClear": 4 } }

 

aws:all-bytes-inmore info (4)
aws:all-bytes-in

The number of inbound bytes to a device during a given time period.

more info (4)

Use this metric to specify the maximum or minimum amount of in-bound traffic that a device should receive, measured in bytes in a given period of time.

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: bytes

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "TCP inbound traffic", "metric": "aws:all-bytes-in", "criteria": { "comparisonOperator": "less-than", "value": { "count": 4096 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 3 } }

Example using a statisticalThreshold:

{ "name": "TCP inbound traffic", "metric": "aws:all-bytes-in", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 3 } }

 

aws:all-packets-outmore info (5)
aws:all-packets-out

The number of outbound packets from a device during a given time period.

more info (5)

Use this metric to specify the maximum or minimum amount of total outbound traffic that a device should send in a given period of time.

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: packets

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "TCP outbound traffic", "metric": "aws:all-packets-out", "criteria": { "comparisonOperator": "less-than", "value": { "count": 100 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 3 } }

Example using a statisticalThreshold:

{ "name": "TCP outbound traffic", "metric": "aws:all-packets-out", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 3 } }

 

aws:all-packets-inmore info (6)
aws:all-packets-in

The number of inbound packets to a device during a given time period.

more info (6)

Use this metric to specify the maximum or minimum amount of total inbound traffic that a device should receive in a given period of time.

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: packets

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "TCP inbound traffic", "metric": "aws:all-packets-in", "criteria": { "comparisonOperator": "less-than", "value": { "count": 100 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

Example using a statisticalThreshold:

{ "name": "TCP inbound traffic", "metric": "aws:all-packets-in", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

 

aws:num-authorization-failuresmore info (7)
aws:num-authorization-failures

The number of authorization failures during a given time period.

more info (7)

Use this metric to specify the maximum number of authorization failures allowed for each device in a given period of time. An authorization failure occurs when a request from a device to AWS IoT is denied, for example, if a device attempts to publish to a topic for which it does not have sufficient permissions.

Source: cloud-side

Unit: failures

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: failures

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "Authorization Failures", "metric": "aws:num-authorization-failures", "criteria": { "comparisonOperator": "less-than", "value": { "count": 5 }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

Example using a statisticalThreshold:

{ "name": "Authorization Failures", "metric": "aws:num-authorization-failures", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p50" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

 

aws:source-ip-addressmore info (8)
aws:source-ip-address

The IP address from which a device has connected to AWS IoT.

more info (8)

Use this metric to specify a set of whitelisted or blacklisted CIDRs from which each device must or must not connect to AWS IoT.

Source: cloud-side

Operators: in-cidr-set | not-in-cidr-set

Values: a list of CIDRs

Units: n/a

Example:

{ "name": "Blacklisted source IPs", "metric": "aws:source-ip-address", "criteria": { "comparisonOperator": "not-in-cidr-set", "value": { "cidrs": [ "12.8.0.0/16", "15.102.16.0/24" ] } } }

 

aws:destination-ip-addressesmore info (9)
aws:destination-ip-addresses

A set of IP destinations.

more info (9)

Use this metric to specify a set of whitelisted or blacklisted CIDRs that each device must or must not communicate with.

Source: device-side

Operators: in-cidr-set | not-in-cidr-set

Values: a list of CIDRs

Units: n/a

Example:

{ "name": "Blacklisted destination IPs", "metric": "aws:destination-ip-addresses", "criteria": { "comparisonOperator": "not-in-cidr-set", "value": { "cidrs": [ "12.8.0.0/16", "15.102.16.0/24" ] } } }

 

aws:listening-tcp-ports / aws:listening-udp-portsmore info (10)
aws:listening-tcp-ports / aws:listening-udp-ports

The TCP or UDP ports that the device is listening on.

more info (10)

Use this metric to specify a set of whitelisted or blacklisted TCP/UDP ports that each device must or must not listen on.

Source: device-side

Operators: in-port-set | not-in-port-set

Values: a list of ports

Units: n/a

Example:

{ "name": "Listening TCP Ports", "metric": "aws:listening-tcp-ports", "criteria": { "comparisonOperator": "in-port-set", "value": { "ports": [ 443, 80 ] } } }

 

aws:num-listening-tcp-ports / aws:num-listening-udp-portsmore info (11)
aws:num-listening-tcp-ports / aws:num-listening-udp-ports

The number of TCP or UDP ports the device is listening on.

more info (11)

Use this metric to specify the maximum or minimum number of TCP or UDP ports that each device should listen on.

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: ports

Example:

{ "name": "Max TCP Ports", "metric": "aws:num-listening-tcp-ports", "criteria": { "comparisonOperator": "less-than-equals", "value": { "count": 4 }, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

Example using a statisticalThreshold:

{ "name": "Max TCP Ports", "metric": "aws:num-listening-tcp-ports", "criteria": { "comparisonOperator": "less-than-equals", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 2, "consecutiveDatapointsToClear": 1 } }

 

aws:num-established-tcp-connectionsmore info (12)
aws:num-established-tcp-connections

The number of TCP connections for a device.

more info (12)

Use this metric to specify the maximum or minimum number of active TCP connections that each device should have. (All TCP states)

Source: device-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: connections

Example:

{ "name": "TCP Connection Count", "metric": "aws:num-established-tcp-connections", "criteria": { "comparisonOperator": "less-than", "value": { "count": 3 }, "consecutiveDatapointsToAlarm": 3, "consecutiveDatapointsToClear": 3 } }

Example using a statisticalThreshold:

{ "name": "TCP Connection Count", "metric": "aws:num-established-tcp-connections", "criteria": { "comparisonOperator": "less-than", "statisticalThreshold": { "statistic": "p90" }, "durationSeconds": 900, "consecutiveDatapointsToAlarm": 3, "consecutiveDatapointsToClear": 3 } }

 

aws:num-connection-attemptsmore info (13)
aws:num-connection-attempts

The number of times a device has attempted to make a connection in a given time period.

more info (13)

Use this metric to specify the maximum or minimum number of connection attempts for each device. Both successful and unsuccessful attempts are counted.

Source: cloud-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: connection attempts

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "Connection Attempts", "metric": "aws:num-connection-attempts", "criteria": { "comparisonOperator": "greater-than", "value": { "count": 5 }, "durationSeconds": 600, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 2 } }

Example using a statisticalThreshold:

{ "name": "Connection Attempts", "metric": "aws:num-connection-attempts", "criteria": { "comparisonOperator": "greater-than", "statisticalThreshold": { "statistic": "p10" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 2 } }

 

aws:num-disconnectsmore info (14)
aws:num-disconnects

The number of times a device has disconnected from AWS IoT during a given time period.

more info (14)

Use this metric to specify the maximum or minimum number of times a device has disconnected from AWS IoT during a given time period.

Source: cloud-side

Operators: less-than | less-than-equals | greater-than | greater-than-equals

Value: a non-negative integer

Units: disconnects

Duration: a non-negative integer, valid values are 300, 600, 900, 1800 or 3600 seconds

Example:

{ "name": "Disconnections", "metric": "aws:num-disconnects", "criteria": { "comparisonOperator": "greater-than", "value": { "count": 5 }, "durationSeconds": 600, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 2 } }

Example using a statisticalThreshold:

{ "name": "Disconnections", "metric": "aws:num-disconnects", "criteria": { "comparisonOperator": "greater-than", "statisticalThreshold": { "statistic": "p10" }, "durationSeconds": 300, "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 2 } }

How To Use AWS IoT Device Defender Detect

  1. You can use AWS IoT Device Defender Detect with just cloud-side metrics, but if you plan to use device reported metrics, you must first deploy an agent on your AWS IoT connected devices or device gateways. See Sending Metrics from Devices.

  2. You should consider viewing the actual metrics that your devices generate before you define behaviors and before you generate alarms. You can have AWS IoT collect metrics from your devices to see what might be usual, or unusual behavior for a group of devices, or for all devices in your account, without generating alarms. Use CreateSecurityProfile but specify only those additionalMetricsToRetain in which you are interested. Do not specify any behaviors at this point.

  3. Create a set of behaviors for your security profile. Behaviors contain metrics that specify normal behavior for a group of devices or for all devices in your account. Metrics has more information, including examples. After you have created a set of behaviors, you can validate them with ValidateSecurityProfileBehaviors.

  4. Use CreateSecurityProfile to create a security profile that includes your behaviors. You can have alerts sent to a target (an SNS topic) when a device violates a behavior by using the alertTargets parameter. (If you do send alerts using SNS be aware that these will count against your account's SNS limit. It is possible for a large burst of violations to exhaust your capacity.) You can also check for violations using CloudWatch metrics (see AWS IoT Metrics).

  5. Use AttachSecurityProfile to attach the security profile to a group of devices (a thing group) or to all the devices in your account. AWS IoT Device Defender Detect will begin checking for abnormal behavior and will send alerts if any behavior violations are detected.

    To attach a security profile to a group of devices, you must specify the ARN of the thing group which contains them. A thing group ARN has the following format:

    arn:aws:iot:<region>:<accountid>:thinggroup/<thing-group-name>

    To attach a security profile to all of the devices in an account, you must specify an ARN with the following format:

    arn:aws:iot:<region>:<accountid>:all/things
  6. You can also keep track of violations with ListActiveViolations which allows you to see what violations have been detected for a given security profile or target device.

    Use ListViolationEvents to see what violations have been detected during a specified time period. You can filter these results by a given security profile or device.

  7. If your devices violate the behaviors you have defined too often, or not often enough, you will want to fine-tune the behavior definitions.

  8. To review the security profiles you have set up and the devices that are being monitored, use ListSecurityProfiles, ListSecurityProfilesForTarget, and ListTargetsForSecurityProfile.

    You can get more details about a particular security profile with DescribeSecurityProfile.

  9. To make changes to a security profile, use UpdateSecurityProfile. You may detach a security profile from an account or target thing group using DetachSecurityProfile or delete a security profile entirely with DeleteSecurityProfile.

Permissions

This section contains information on how to set up the AWS IAM roles and policies required to manage AWS IoT Device Defender Detect. For more information on AWS IAM, see the AWS Identity and Access Management User Guide.

Give AWS IoT Device Defender Detect permission to publish alerts to an SNS topic.

If you use the alertTargets parameter in CreateSecurityProfile, you must specify an IAM Role with two policies, a permissions policy and a trust policy. The permissions policy grants permission to AWS IoT Device Defender to publish notifications to your SNS topic. The trust policy grants AWS IoT Device Defender permission to assume the required role.

permissions policy
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "sns:Publish" ], "Resource":[ "arn:aws:sns:region:account-id:your-topic-name" ] } ] }
trust policy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
pass role policy

You also need an IAM permissions policy attached to the IAM user that allows the user to pass roles. See Granting a User Permissions to Pass a Role to an AWS Service.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:PassRole" ], "Resource": "arn:aws:iam::>account-id<:role/Role_To_Pass" } ] }

Service Limits

  • The maximum number of security profiles per target (thing group or user account) is 5.

  • The maximum number of behaviors per security profile is 100.

  • The maximum number of value elements (counts, IP addresses, ports) per security profile is 1000.

  • Device metric reporting may be throttled to one metric report per 5 minutes per device. So limit your device reporting to one metric report every 5 minutes to avoid throttling.

  • AWS IoT Device Defender Detect violations are stored for 90 days after they have been generated.

Sending Metrics from Devices

AWS IoT Device Defender Detect can collect, aggregate, and monitor metrics data generated by AWS IoT devices to identify devices that are exhibiting abnormal behavior. This section contains information on how to send metrics from a device to AWS IoT Device Defender.

You must securely deploy an agent on your AWS IoT connected devices or device gateways to collect device-side metrics. AWS IoT Device Defender provides sample agents to use as examples when creating your own. If you are unable to provide device metrics, you can still get limited functionality based on cloud-side metrics.

Please note the following:

  • A sample device metric reporting agent is currently available in C at https://github.com/aws-samples/aws-iot-device-defender-agent-c. There is also a sample device metric reporting agent available in Python on GitHub at https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python (specifically here).

  • To use the sample agents or create your own custom agent, you must install the AWS IoT Device SDK. To see the links for your development language of choice, go to AWS IoT Core Resources.

  • All agents must create a connection to AWS IoT and publish metrics to one of these reserved Device Defender MQTT topics:

    $aws/things/THING_NAME/Defender/metrics/json

    or

    $aws/things/THING_NAME/Defender/metrics/cbor

    Device Defender will reply with the receipt status of your metrics reports using one of these topics:

    $aws/things/THING_NAME/Defender/metrics/json/accepted
    $aws/things/THING_NAME/Defender/metrics/cbor/accepted
    $aws/things/THING_NAME/Defender/metrics/json/rejected
    $aws/things/THING_NAME/Defender/metrics/cbor/rejected
  • In order to report metrics, a device must be registered as a thing in AWS IoT.

  • A device should, generally, send a metric report once every 5 minutes. Devices are throttled to one metric report every 5 minutes (a device may not make more than one metric report every 5 minutes).

  • Devices must report current metrics; historical metrics reporting is not supported.

  • You can use Jobs to set the metrics reporting interval of your device metric reporting agent instances. An example of how to do this is included with the AWS Device Defender Agent C samples. See the README.md for more information.

Device Metrics Document Specification

Overall Structure:

Long Name

Short Name

Required

Type

Constraints

Notes

header

hed

Y

Object

Complete block required for well-formed report.

metrics

met

Y

Object

Complete block required for well-formed report.

Header Block:

Long Name

Short Name

Required

Type

Constraints

Notes

report_id

rid

Y

Integer

Monotonically increasing value, epoch timestamp recommended

version

v

Y

String

Major.Minor

minor increments with addition of field, major increments if metrics removed

Metrics Block:

TCP Connections:

Long Name

Short Name

Parent Element

Required

Type

Constraints

Notes

tcp_connections

tc

metrics

N

Object

established_connections

ec

tcp_connections

N

List<Connection>

ESTABLISHED TCP State

connections

cs

established_connections

N

List<Object>

remote_addr

rad

connections

Y

Number

ip:port

ip can be ipv6 or ipv4

local_port

lp

connections

N

Number

>= 0

local_interface

li

connections

N

String

interface name

total

t

established_connections

N

Number

>= 0

Number of established connections

Listening TCP Ports:

Long Name

Short Name

Parent Element

Required

Type

Constraints

Notes

listening_tcp_ports

tp

metrics

N

Object

ports

pts

listening_tcp_ports

N

List<Port>

> 0

port

pt

ports

N

Number

> 0

ports should be numbers > 0

interface

if

ports

N

String

interface name

total

t

listening_tcp_ports

N

Number

>= 0

Listening UDP Ports:

Long Name

Short Name

Parent Element

Required

Type

Constraints

Notes

listening_udp_ports

up

metrics

N

Object

ports

pts

listening_udp_ports

N

List<Port>

> 0

port

pt

ports

N

Number

> 0

ports should be numbers > 0

interface

if

ports

N

String

interface name

total

t

listening_udp_ports

N

Number

>= 0

Network Stats:

Long Name

Short Name

Parent Element

Required

Type

Constraints

Notes

network_stats

ns

metrics

N

Object

bytes_in

bi

network_stats

N

Number

Delta Metric, >= 0

bytes_out

bo

network_stats

N

Number

Delta Metric, >= 0

packets_in

pi

network_stats

N

Number

Delta Metric, >= 0

packets_out

po

network_stats

N

Number

Delta Metric, >= 0

Example JSON structure using long names:

{ "header": { "report_id": 1530304554, "version": "1.0" }, "metrics": { "listening_tcp_ports": { "ports": [ { "interface": "eth0", "port": 24800 }, { "interface": "eth0", "port": 22 }, { "interface": "eth0", "port": 53 } ], "total": 3 }, "listening_udp_ports": { "ports": [ { "interface": "eth0", "port": 5353 }, { "interface": "eth0", "port": 67 } ], "total": 2 }, "network_stats": { "bytes_in": 29358693495, "bytes_out": 26485035, "packets_in": 10013573555, "packets_out": 11382615 }, "tcp_connections": { "established_connections": { "connections": [ { "local_interface": "eth0", "local_port": 80, "remote_addr": "192.168.0.1:8000" }, { "local_interface": "eth0", "local_port": 80, "remote_addr": "192.168.0.1:8000" } ], "total": 2 } } } }

Example JSON structure using short names:

{ "hed": { "rid": 1530305228, "v": "1.0" }, "met": { "tp": { "pts": [ { "if": "eth0", "pt": 24800 }, { "if": "eth0", "pt": 22 }, { "if": "eth0", "pt": 53 } ], "t": 3 }, "up": { "pts": [ { "if": "eth0", "pt": 5353 }, { "if": "eth0", "pt": 67 } ], "t": 2 }, "ns": { "bi": 29359307173, "bo": 26490711, "pi": 10014614051, "po": 11387620 }, "tc": { "ec" : { "cs": [ { "li": "eth0", "lp": 80, "rad": "192.168.0.1:8000" }, { "li": "eth0", "lp": 80, "rad": "192.168.0.1:8000" } ], "t": 2 } } } }