Detect - AWS IoT

Detect

AWS IoT Device Defender Detect lets you identify unusual behavior that might 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 that you install on your devices) you can detect:

  • Changes in connection patterns.

  • Devices that communicate to unauthorized or unrecognized endpoints.

  • 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 through Amazon CloudWatch metrics and Amazon Simple Notification Service notifications.

AWS IoT Device Defender Detect can detect 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 (for example, from a rogue device that can result in excessive 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 that 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 AWS IoT Device Defender Detect alerts you to the attack surface, you can 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) that might indicate a security breach. For example, a higher than expected number of TCP connections might indicate a device is being used for a DDoS attack. A process listening on a port other than the one you expect might indicate a backdoor installed on a device for remote control. You can use AWS IoT Device Defender 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).

You can enable machine learning (ML)-based threat detection to automatically identify potential threats.

Detect an incorrectly configured device

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

Concepts

metric

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

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 through AWS IoT.

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 the AWS IoT SDK on your AWS IoT connected devices or device gateways to collect the metrics and send them to AWS IoT. See Sending metrics from devices.

dimension

You can define a dimension to adjust the scope of a behavior. For example, you can define a topic filter dimension that applies a behavior to MQTT topics that match a pattern. For information about defining a dimension for use in a security profile, see CreateDimension.

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 which actions to take when an anomaly is detected. You can use the AWS IoT console or API commands to create a security profile and associate it with a group of devices. 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 doesn't match a defined behavior statement triggers an alert.

alert

When an anomaly is detected, an alert notification can be sent through a CloudWatch metric (see Using AWS IoT metrics) or an SNS notification. An alert notification is also displayed in the AWS IoT console along with 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 for the behavior.

metric

The name of the metric used (that is, what is measured by the behavior).

dimension

You can define a dimension to adjust the scope of a behavior. For example, you can define a topic filter dimension that applies a behavior to MQTT topics that match a pattern. To define a dimension for use in a security profile, see CreateDimension.

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 that 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, the device is in violation of the behavior.

A percentile indicates the percentage of all the measurements considered that 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 that 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 data points, an alarm occurs. If not specified, the default is 1. (This differs from the AWS 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 data points, the alarm is cleared. If not specified, the default is 1. (This differs from the AWS IoT console where a value of 3 is presented by default, but can be overridden.)

Metrics

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 five-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-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 can 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-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 outbound 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-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 inbound 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-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-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-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-address

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

More info (8)

Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as 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": "Denied 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-addresses

A set of IP destinations.

More info (9)

Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as blacklisted) CIDRs with which each device must or must not communicate.

Source: device-side

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

Values: a list of CIDRs

Units: n/a

Example:

Example

{ "name": "Denied 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-ports

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

More info (10)

Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as 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-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

Example:

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-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-attempts

The number of times a device attempts 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. 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-disconnects

The number of times a device disconnects 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 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 } }

Scoping metrics in security profiles using dimensions

Dimensions are attributes that you can define to get more precise data about metrics and behaviors in your security profile. You define the scope by providing a value or pattern that is used as a filter. For example, you can define a topic filter dimension that applies a metric only to MQTT topics that match a particular value, such as "data/bulb/+/activity". For information about defining a dimension that you can use in your security profile, see CreateDimension.

Dimension values support MQTT wildcards. MQTT wildcards help you subscribe to multiple topics simultaneously. There are two different kinds of wildcards: single-level (+) and multi-level (#). For example, the dimension value Data/bulb/+/activity creates a subscription that matches all topics that exist on the same level as the +. Dimension values also supports the MQTT client ID substitution variable ${iot:ClientId}.

Dimensions of type TOPIC_FILTER are compatible with the following set of cloud-side metrics:

  • Number of messages sent

  • Number of messages received

  • Message byte size

  • Source IP address

  • Number of authorization failures

How to use dimensions on the AWS CLI

To create and apply a dimension to a security profile behavior

  1. First create the dimension before attaching it to a security profile. Use the CreateDimension command to create a dimension:

    aws iot create-dimension \ --name TopicFilterForAuthMessages \ --type TOPIC_FILTER \ --string-values device/+/auth

    The output of this command looks like the following:

    { "arn": "arn:aws:iot:us-west-2:123456789012:dimension/TopicFilterForAuthMessages", "name": "TopicFilterForAuthMessages" }
  2. Either add the dimension to an existing security profile using UpdateSecurityProfile, or add the dimension to a new security profile using CreateSecurityProfile. In the following example, we create a new security profile that checks if messages to TopicFilterForAuthMessages are under 128 bytes, and retains the number of messages sent to non-auth topics.

    aws iot create-security-profile \ --security-profile-name ProfileForConnectedDevice \ --security-profile-description "Check to see if messages to TopicFilterForAuthMessages are under 128 bytes and retains the number of messages sent to non-auth topics." \ --behaviors "[{\"name\":\"CellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}},{\"name\":\"Authorization\",\"metric\":\"aws:num-authorization-failures\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":10},\"durationSeconds\":300,\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]" \ --additional-metrics-to-retain-v2 "[{\"metric\": \"aws:num-authorization-failures\",\"metricDimension\": {\"dimensionName\": \"TopicFilterForAuthMessages\",\"operator\": \"NOT_IN\"}}]"

    The output of this command looks like the following:

    { "securityProfileArn": "arn:aws:iot:us-west-2:1234564789012:securityprofile/ProfileForConnectedDevice", "securityProfileName": "ProfileForConnectedDevice" }

    You can also load a parameter from a file instead of typing it all as a command line parameter value to save time. For more information, see Loading AWS CLI Parameters from a File. The following shows the behavior parameter in expanded JSON format:

    [ { "criteria": { "comparisonOperator": "less-than", "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "value": { "count": 128 } }, "metric": "aws:message-byte-size", "metricDimension": { "dimensionName:": "TopicFilterForAuthMessages" }, "name": "CellularBandwidth" } ]

To view security profiles with a dimension

  • Use the ListSecurityProfiles command to view security profiles with a certain dimension:

    aws iot list-security-profiles \ --dimension-name TopicFilterForAuthMessages

    The output of this command looks like the following:

    { "securityProfileIdentifiers": [ { "name": "ProfileForConnectedDevice", "arn": "arn:aws:iot:us-west-2:1234564789012:securityprofile/ProfileForConnectedDevice" } ] }

To update your dimension

  • Use the UpdateDimension command to update a dimension:

    aws iot update-dimension \ --name TopicFilterForAuthMessages \ --string-values device/${iot:ClientId}/auth

    The output of this command looks like the following:

    { "name": "TopicFilterForAuthMessages", "lastModifiedDate": 1585866222.317, "stringValues": [ "device/${iot:ClientId}/auth" ], "creationDate": 1585854500.474, "type": "TOPIC_FILTER", "arn": "arn:aws:iot:us-west-2:1234564789012:dimension/TopicFilterForAuthMessages" }

To delete a dimension

  1. To delete a dimension, first detach it from any security profiles that it's attached to. Use the ListSecurityProfiles command to view security profiles with a certain dimension.

  2. To remove a dimension from a security profile, use the UpdateSecurityProfile command. Enter all information that you want to keep, but exclude the dimension:

    aws iot update-security-profile \ --security-profile-name ProfileForConnectedDevice \ --security-profile-description "Check to see if authorization fails 10 times in 5 minutes or if cellular bandwidth exceeds 128" \ --behaviors "[{\"name\":\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}},{\"name\":\"Authorization\",\"metric\":\"aws:num-authorization-failures\",\"criteria\":{\comparisonOperator\":\"less-than\",\"value\"{\"count\":10},\"durationSeconds\":300,\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]"

    The output of this command looks like the following:

    { "behaviors": [ { "metric": "aws:message-byte-size", "name": "CellularBandwidth", "criteria": { "consecutiveDatapointsToClear": 1, "comparisonOperator": "less-than", "consecutiveDatapointsToAlarm": 1, "value": { "count": 128 } } }, { "metric": "aws:num-authorization-failures", "name": "Authorization", "criteria": { "durationSeconds": 300, "comparisonOperator": "less-than", "consecutiveDatapointsToClear": 1, "consecutiveDatapointsToAlarm": 1, "value": { "count": 10 } } } ], "securityProfileName": "ProfileForConnectedDevice", "lastModifiedDate": 1585936349.12, "securityProfileDescription": "Check to see if authorization fails 10 times in 5 minutes or if cellular bandwidth exceeds 128", "version": 2, "securityProfileArn": "arn:aws:iot:us-west-2:123456789012:securityprofile/Preo/ProfileForConnectedDevice", "creationDate": 1585846909.127 }
  3. After the dimension is detached, use the DeleteDimension command to delete the dimension:

    aws iot delete-dimension \ --name TopicFilterForAuthMessages

How to use dimensions in the console

To create and apply a dimension to a security profile behavior

  1. In the AWS IoT console, in the navigation pane, expand Defend, expand Detect, and select Security profiles.

  2. On the Security profiles page, choose Create to add a new security profile, or Edit to apply a dimension to an existing security profile.

  3. On the Expected behaviors page, select one of the five cloud-side metrics dimensions supports under Metric. The Dimension and Dimension operator boxes display. For information about supported cloud-side metrics, see Scoping metrics in security profiles using dimensions.

  4. Under the Dimension dropdown, select Add dimension.

  5. On the Create a new dimension page, enter details for your new dimension. Dimensions values supports MQTT wildcards # and + and the MQTT client ID substitution variable ${iot:ClientId}.

  6. Choose Save.

  7. You can also add dimensions to metrics under Additional Metrics to retain.

  8. Enter the information in the other required fields to finish creating the behavior, and choose Next.

  9. Complete the remaining steps to finish creating a security profile.

To view your violations

  1. In the AWS IoT console, in the navigation pane, expand Defend then Detect. Then select Violations.

  2. In the Behavior column, hover over the behavior you want to see the violation information for.

To view and update your dimensions

  1. In the AWS IoT console, in the navigation pane, expand Defend, expand Detect, and select Dimensions.

  2. Select the dimension that you'd like to edit.

  3. Select Actions, Edit.

    
            Image of dimensions dropdown in console.

To delete a dimension

  1. In the AWS IoT console, in the navigation pane, expand Defend, expand Detect, and select Dimensions.

  2. Select the dimension that you want to delete.

  3. Confirm that the dimension isn't attached to a security profile by checking the Used in column. If the dimension is attached to a security profile, open the Security profiles page on the left, and edit the security profiles that the dimension is attached to. When you delete the dimesion, you also delete the behavior. If you want to keep the behavior, choose the ellipsis, then choose Copy. Then you can proceed with deleting the behavior. If you want to delete another dimension, follow the steps in this section.

    
            Image of dimensions delete page.
  4. Select Actions, Delete.

Monitoring the behavior of unregistered devices

AWS IoT Device Defender Detect makes it possible to identify unusual behaviors for devices that are not registered in the AWS IoT registry. You can define security profiles that are specific to one of the following target types:

  • All devices

  • All registered devices (things in the AWS IoT registry)

  • All unregistered devices

  • Devices in a thing group

A security profile defines a set of expected behaviors for devices in your account and specifies the actions to take when an anomaly is detected. Security profiles should be attached to the most specific targets to give you granular control over which devices are being evaluated against that profile.

Unregistered devices must provide a consistent MQTT client identifier or thing name (for devices that report device metrics) over the device lifetime so all violations and metrics are attributed to the same device.

Important

Messages reported by devices are rejected if the thing name contains control characters or if the thing name is longer than 128 bytes of UTF-8 encoded characters.

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 the AWS IoT SDK on your AWS IoT connected devices or device gateways. For more information, see Sending metrics from devices.

  2. Consider viewing the metrics that your devices generate before you define behaviors and create alarms. AWS IoT can collect metrics from your devices so you can first identify usual or unusual behavior for a group of devices, or for all devices in your account. Use CreateSecurityProfile, but specify only those additionalMetricsToRetain that you're interested in. Don't specify behaviors at this point.

    Use the AWS IoT console to look at your device metrics to see what constitutes typical behavior for your devices.

  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. For more information and examples, see Metrics. After you create a set of behaviors, you can validate them with ValidateSecurityProfileBehaviors.

  4. Use the CreateSecurityProfile action to create a security profile that includes your behaviors. You can use the alertTargets parameter to have alerts sent to a target (an SNS topic) when a device violates a behavior. (If you send alerts using SNS, be aware that these count against your AWS account's SNS topic quota. It's possible that a large burst of violations can exceed your SNS topic quota. You can also use CloudWatch metrics to check for violations. For more information, see .

  5. Use the AttachSecurityProfile action to attach the security profile to a group of devices (a thing group), all registered things in your account, all unregistered things, or all devices. AWS IoT Device Defender Detect starts checking for abnormal behavior and, if any behavior violations are detected, sends alerts. You might want to attach a security profile to all unregistered things if, for example, you expect to interact with mobile devices that are not in your account's thing registry. You can define different sets of behaviors for different groups of devices to meet your needs.

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

    arn:aws:iot:region:account-id:thinggroup/thing-group-name

    To attach a security profile to all of the registered things in an AWS account (ignoring unregistered things), you must specify an ARN with the following format.

    arn:aws:iot:region:account-id:all/registered-things

    To attach a security profile to all unregistered things, you must specify an ARN with the following format.

    arn:aws:iot:region:account-id:all/unregistered-things

    To attach a security profile to all devices, you must specify an ARN with the following format.

    arn:aws:iot:region:account-id:all/things
  6. You can also keep track of violations with the ListActiveViolations action, which lets you to see which violations were detected for a given security profile or target device.

    Use the ListViolationEvents action to see which violations were detected during a specified time period. You can filter these results by security profile or device.

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

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

    Use the DescribeSecurityProfile action to get more details about a security profile.

  9. To update a security profile, use the UpdateSecurityProfile action. Use the DetachSecurityProfile action to detach a security profile from an account or target thing group. Use the DeleteSecurityProfile action to delete a security profile entirely.

Permissions

This section contains information about how to set up the IAM roles and policies required to manage AWS IoT Device Defender Detect. For more information, see the IAM 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.

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

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" } ] }

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 exhibit abnormal behavior. This section shows you how to send metrics from a device to AWS IoT Device Defender.

You must securely deploy the AWS IoT SDK 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 you create your own. If you can't provide device metrics, you can still get limited functionality based on cloud-side metrics.

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, see the greengrass_defender_agent.py file.

  • To use the sample agents or create your own custom agent, you must install the AWS IoT Device SDK. To find resources for your development language, see AWS IoT Core Resources.

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

    $aws/things/THING_NAME/defender/metrics/json

    or

    $aws/things/THING_NAME/defender/metrics/cbor

    AWS IoT Device Defender uses one of these topics to reply with the receipt status of your metrics reports:

    $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
  • 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 can't make more than one metric report every 5 minutes.)

  • Devices must report current metrics. Historical metrics reporting isn't supported.

  • You can use Jobs to set the metrics reporting interval of your device metric reporting agent instances. An example is included with the AWS IoT Device Defender Agent C samples. For more information, see the README.md.

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 greater than 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 greater than 0

interface

if

ports

N

String

Interface name

total

t

listening_udp_ports

N

Number

>= 0

Network statistics

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

The following JSON structure uses 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 } } } }