# 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 alarms 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 alarms 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 alarm 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.
## 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.
# Security use cases
This section describes the different types of attacks that threaten your device fleet and the recommended metrics you can use to monitor for these attacks. We recommend using metric anomalies as a starting point to investigate security issues, but you should not base your determination of any security threats solely on a metric anomaly.
To investigate an anomaly alarm, correlate the alarm details with other contextual information such as device attributes, device metric historical trends, Security Profile metric historical trends, custom metrics, and logs to determine if a security threat is present.
## Cloud-side use cases
Device Defender can monitor the following use cases on the AWS IoT cloud side.
**Intellectual property theft:**
Intellectual property theft involves stealing a person's or companies' intellectual properties, including trade secrets, hardware, or software. It often occurs during the manufacturing stage of devices. Intellectual property theft can come in the form of piracy, device theft, or device certificate theft. Cloud-based intellectual property theft can occur due to the presence of policies that permit unintended access to IoT resources. You should review your [IoT policies](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) and turn on [Audit overly permissive checks](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-audit-checks.html) to identify overly permissive policies.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**MQTT-based data exfiltration: **
Data exfiltration occurs when a malicious actor carries out an unauthorized data transfer from an IoT deployment or from a device. The attacker launches this type of attacks through MQTT against cloud-side data sources.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Impersonation:**
An impersonation attack is where attackers pose as known or trusted entities in an effort to access AWS IoT cloud-side services, applications, data, or engage in command and control of IoT devices.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Cloud Infrastructure abuse:**
Abuse to AWS IoT cloud services occurs when publishing or subscribing to topics with a high message volume or with messages in large sizes. Overly permissive policies or device vulnerability exploit for command and control can also cause cloud infrastructure abuse. One of the main objectives of this attack is to increase your AWS bill. You should review your [IoT policies](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) and turn on [Audit overly permissive checks](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-audit-checks.html) to identify overly permissive policies.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
## Device-side use cases
Device Defender can monitor the following use cases on your device side.
**Denial-of-service attack:**
A denial-of-service (DoS) attack is aimed at shutting down a device or network, making the device or network inaccessible to their intended users. DoS attacks block access by flooding the target with traffic, or sending it requests that start a system slow-down or cause the system to fail. Your IoT devices can be used in DoS attacks.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Lateral threat escalation:**
Lateral threat escalation usually begins with an attacker gaining access to one point of a network, for example a connected device. The attacker then tries to increase their level of privileges, or their access to other devices through methods such as stolen credentials or vulnerability exploits.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Data exfiltration or surveillance:**
Data exfiltration occurs when malware or a malicious actor carries out an unauthorized data transfer from a device or a network endpoint. Data exfiltration normally serves two purposes for the attacker, obtaining data or intellectual property, or conducting reconnaissance of a network. Surveillance means that malicious code is used to monitor user activities for the purpose of stealing credentials and gathering information. The metrics below can provide a starting point of investigating either type of attacks.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Cryptocurrency mining**
Attackers leverage processing power from devices to mine cryptocurrency. Crypto-mining is a computationally intensive process, typically requiring network communication with other mining peers and pools.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
**Command and control, malware and ransomware**
Malware or ransomware restricts your control over your devices, and limits your device functionality. In the case of a ransomware attack, data access would be lost due to encryption the ransomware uses.
****Related metrics:****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/dd-detect-security-use-cases.html)
# Concepts
**metric**
AWS IoT Device Defender Detect uses metrics to detect anomalous behavior of devices. 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. ML Detect supports 6 cloud-side metrics and 7 device-side metrics. For a list of supported metrics for ML Detect, see [Supported metrics](dd-detect-ml.md#dd-detect-ml-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](detect-device-side-metrics.md#DetectMetricsMessages).
**Security Profile**
A Security Profile defines anomalous behaviors for a group of devices (a [Static thing group](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html)) 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 anomalous. Any device action that doesn’t match a behavior triggers an alert. A Rules Detect behavior consists of a metric and an absolute-value or statistical threshold with an operator (for example, less than or equal to, greater than or equal to), which describe the expected device behavior. An ML Detect behavior consists of a metric and an ML Detect configuration, which set an ML model to learn the normal behavior of devices.
**ML model**
An ML model is a machine learning model created to monitor each behavior a customer configures. The model trains on metric data patterns from targeted device groups and generates three anomaly confidence thresholds (high, medium, and low) for the metric-based behavior. It inferences anomalies based on ingested metric data at the device level. In the context of ML Detect, one ML model is created to evaluate one metric-based behavior. For more information, see [ML Detect](dd-detect-ml.md).
**confidence level**
ML Detect supports three confidence levels: `High`, `Medium`, and `Low`. `High` confidence means low sensitivity in anomalous behavior evaluation and frequently a lower number of alarms. `Medium` confidence means medium sensitivity and `Low` confidence means high sensitivity and frequently a higher number of alarms.
**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](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateDimension.html).
**alarm**
When an anomaly is detected, an alarm notification can be sent through a CloudWatch metric (see [Monitor AWS IoT alarms and metrics using Amazon CloudWatch](https://docs.aws.amazon.com/iot/latest/developerguide/monitoring-cloudwatch.html) in the *AWS IoT Core Developer Guide*) or an SNS notification. An alarm notification is also displayed in the AWS IoT console along with information about the alarm, and a history of alarms for the device. An alarm is also sent when a monitored device stops exhibiting anomalous behavior or when it had been causing an alarm but stops reporting for an extended period.
**alarm verification state**
After an alarm has been created, you can verify the alarm as True positive, Benign positive, False positive, or Unknown. You can also add a description to your alarm verification state. You can view, organize, and filter AWS IoT Device Defender alarms by using one of the four verification states. You can use alarm verification states and related descriptions to inform members of your team. This helps your team to take follow-up actions, for example, performing mitigation actions on True positive alarms, skipping Benign positive alarms, or continuing investigation on Unknown alarms. The default verification state for all alarms is Unknown.
**alarm suppression**
Manage Detect alarm SNS notifications by setting behavior notification to `on` or `suppressed`. Suppressing alarms doesn't stop Detect from performing device behavior evaluations; Detect continues to flag anomalous behaviors as violation alarms. However, suppressed alarms wouldn't be forwarded for SNS notification. They can only be accessed through the AWS IoT console or API.
# 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. Behaviors fall into two categories: Rules Detect behaviors and ML Detect behaviors. With Rules Detect behaviors, you define how your devices should behave whereas ML Detect uses ML models built on historical device data to evaluate how your devices should behave.
A Security Profile can be one of two threshold types: **ML** or **Rule-based**. ML Security Profiles automatically detect device-level operational and security anomalies across your fleet by learning from past data. Rule-based Security Profiles require that you manually set static rules to monitor your device behaviors.
The following describes some of the fields that are used in the definition of a `behavior`:Common to Rules Detect and ML Detect
**`name`**
The name for the behavior.
**`metric`**
The name of the metric used (that is, what is measured by the behavior).
**`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.
**`consecutiveDatapointsToClear`**
If an alarm 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.
**`threshold type`**
A Security Profile can be one of two threshold types: ML or Rules based. ML Security Profiles automatically detect device-level operational and security anomalies across your fleet by learning from past data. Rule-based Security Profiles require that you manually set static rules to monitor your device behaviors.
**`alarm suppressions`**
You can manage Detect alarm Amazon SNS notifications by setting behavior notification to `on` or `suppressed`. Suppressing alarms doesn't stop Detect from performing device behavior evaluations; Detect continues to flag anomalous behaviors as violation alarms. However, suppressed alarms aren't forwarded for Amazon SNS notifications. They can be accessed only through the AWS IoT console or API.Rules Detect
`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](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateDimension.html). Applies to Rules Detect only.
`criteria`
The criteria that determine if a device is behaving normally in regard to the `metric`.
In the AWS IoT console, you can choose **Alert me** to be notified through Amazon SNS when AWS IoT Device Defender detects that a device is behaving anomalously.
`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](https://en.wikipedia.org/wiki/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.ML Detect
`ML Detect confidence`
ML Detect supports three confidence levels: `High`, `Medium`, and `Low`. `High` confidence means low sensitivity in anomalous behavior evaluation and frequently a lower number of alarms, `Medium` confidence means medium sensitivity, and `Low` confidence means high sensitivity and frequently a higher number of alarms.
# ML Detect
**Note**
ML Detect is not available in the following regions:
Asia Pacific (Malaysia)
With machine learning Detect (ML Detect), you create Security Profiles that use machine learning to learn expected device behaviors by automatically creating models based on historical device data, and assign these profiles to a group of devices or all the devices in your fleet. AWS IoT Device Defender then identifies anomalies and triggers alarms using the ML models.
For information about how to get started with ML Detect, see [ML Detect guide](dd-detect-ml-getting-started.md).
**Topics**
+ [Use cases of ML Detect](#dd-detect-ml-use-cases)
+ [How ML Detect works](#dd-detect-ml-how-it-works)
+ [Minimum requirements](#dd-detect-ml-requirements)
+ [Limitations](#dd-detect-ml-limitations)
+ [Marking false positives and other verification states in alarms](#dd-detect-ml-mark-false-positives)
+ [Supported metrics](#dd-detect-ml-metrics)
+ [Service quotas](#dd-detect-ml-quotas)
+ [ML Detect CLI commands](#dd-detect-ml-cli-commands)
+ [ML Detect APIs](#dd-detect-ml-apis)
+ [Pause or delete an ML Detect Security Profile](#dd-detect-ml-disable-feature)
## Use cases of ML Detect
You can use ML Detect to monitor your fleet devices when it's difficult to set the expected behaviors of devices. For example, to monitor the number of disconnects metric, it might not be clear what is considered an acceptable threshold. In this case, you can enable ML Detect to identify anomalous disconnect metric datapoints based off historical data reported from devices.
Another use case of ML Detect is to monitor device behaviors that change dynamically over time. ML Detect periodically learns the dynamic expected device behaviors based on changing data patterns from devices. For example, device message sent volume could vary between weekdays and weekends, and ML detect will learn this dynamic behavior.
## How ML Detect works
Using ML Detect, you can create behaviors to identify operational and security anomalies across [6 cloud-side metrics](#dd-detect-ml-metrics) and [7 device-side metrics](#dd-detect-ml-metrics). After the initial model training period, ML Detect refreshes the models daily based on the trailing 14 days of data. It monitors datapoints for these metrics with the ML models and triggers an alarm if an anomaly is detected.
ML Detect works best if you attach a Security Profile to a collection of devices with similar expected behaviors. For example, if some of your devices are used at customers’ homes and other devices at business offices, the device behavior patterns might differ significantly between the two groups. You can organize the devices into a *home-device* thing group and an *office-device* thing group. For the best anomaly detection efficacy, attach each thing group to a separate ML Detect Security Profile.
While ML Detect is building the initial model, it requires 14 days and a minimum of 25,000 datapoints per metric over the trailing 14-day period to generate a model. Afterwards, it updates the model every day there is a minimum number of metric datapoints. If the minimum requirement isn't met, ML Detect attempts to build the model the next day, and will retry daily for the next 30 days before discontinuing the model for evaluations.
## Minimum requirements
For training and creating the initial ML model, ML Detect has the following minimum requirements.
**Minimum training period**
It takes 14 days for the initial models to be built. After that, the model refreshes every day with metric data from a 14-day trailing period.
**Minimum total datapoints**
The minimum required datapoints to build an ML model is 25,000 datapoints per metric for the last 14 days. For ongoing training and refreshing of the model, ML Detect requires the minimum datapoints be met from monitored devices. It’s roughly the equivalent of the following setups:
+ 60 devices connecting and having activity on AWS IoT at 45-minute intervals.
+ 40 devices at 30-minute intervals.
+ 15 devices at 10-minute intervals.
+ 7 devices at 5-minute intervals.
**Device group targets**
To collect data, you must have things in the target thing groups for the Security Profile.
After the initial model is created, ML models refresh every day and require at least 25,000 datapoints for 14-day trailing period.
## Limitations
You can use ML Detect with dimensions on the following cloud-side metrics:
+ [Authorization failures (aws:num-authorization-failures)](detect-cloud-side-metrics.md#detect-auth-failures)
+ [Messages received (aws:num-messages-received)](detect-cloud-side-metrics.md#detect-messages-received)
+ [Messages sent (aws:num-messages-sent)](detect-cloud-side-metrics.md#detect-messages-sent)
+ [Message size (aws:message-byte-size)](detect-cloud-side-metrics.md#detect-message-size)
The following metrics are not supported with ML Detect.
**Cloud-side metrics not supported with ML Detect:**
+ [Source IP (aws:source-ip-address)](detect-cloud-side-metrics.md#detect-ip-address)
**Device-side metrics not supported with ML Detect:**
+ [Destination IPs (`aws:destination-ip-addresses`)](detect-device-side-metrics.md#detect-destination-ip-addresses)
+ [Listening TCP ports (`aws:listening-tcp-ports`)](detect-device-side-metrics.md#detect-listening-tcp-ports)
+ [Listening UDP ports (`aws:listening-udp-ports`)](detect-device-side-metrics.md#detect-listening-udp-ports)
Custom metrics only support the **number** type.
## Marking false positives and other verification states in alarms
If you verify that an ML Detect alarm is a false positive through your investigation, you can set the verification state of the alarm to False positive. This can help you and your team identify alarms you don't have to respond to. You can also mark alarms as True positive, Benign positive, or Unknown.
You can mark alarms through the [AWS IoT Device Defender console](https://docs.aws.amazon.com//iot/latest/developerguide/detect-HowToHowTo.html) or by using the [PutVerificationStateOnViolation](https://docs.aws.amazon.com/iot/latest/apireference/API_PutVerificationStateOnViolation.html) API action.
## Supported metrics
You can use the following cloud-side metrics with ML Detect:
+ [Authorization failures (aws:num-authorization-failures)](detect-cloud-side-metrics.md#detect-auth-failures)
+ [Connection attempts (aws:num-connection-attempts)](detect-cloud-side-metrics.md#detect-num-connection-attempts)
+ [Disconnects (aws:num-disconnects)](detect-cloud-side-metrics.md#detect-num-disconnects)
+ [Message size (aws:message-byte-size)](detect-cloud-side-metrics.md#detect-message-size)
+ [Messages sent (aws:num-messages-sent)](detect-cloud-side-metrics.md#detect-messages-sent)
+ [Messages received (aws:num-messages-received)](detect-cloud-side-metrics.md#detect-messages-received)
You can use the following device-side metrics with ML Detect:
+ [Bytes out (`aws:all-bytes-out`)](detect-device-side-metrics.md#detect-all-bytes-out)
+ [Bytes in (`aws:all-bytes-in`)](detect-device-side-metrics.md#detect-all-bytes-in)
+ [Listening TCP port count (`aws:num-listening-tcp-ports`)](detect-device-side-metrics.md#detect-num-listening-tcp-ports)
+ [Listening UDP port count (`aws:num-listening-udp-ports`)](detect-device-side-metrics.md#detect-num-listening-udp-ports)
+ [Packets out (`aws:all-packets-out`)](detect-device-side-metrics.md#detect-all-packets-out)
+ [Packets in (`aws:all-packets-in`)](detect-device-side-metrics.md#detect-all-packets-in)
+ [Established TCP connections count (`aws:num-established-tcp-connections`)](detect-device-side-metrics.md#detect-num-established-tcp-connections)
## Service quotas
For information about ML Detect service quotas and limits, see [AWS IoT Device Defender endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_defender.html).
## ML Detect CLI commands
You can use the following CLI commands to create and manage ML Detect.
+ [create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)
+ [attach-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/attach-security-profile.html)
+ [list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)
+ [describe-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-security-profile.html)
+ [update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)
+ [delete-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-security-profile.html)
+ [get-behavior-model-training-summaries](https://docs.aws.amazon.com/cli/latest/reference/iot/get-behavior-model-training-summaries.html)
+ [list-active-violations](https://docs.aws.amazon.com/cli/latest/reference/iot/list-active-violations.html)
+ [list-violation-events](https://docs.aws.amazon.com/cli/latest/reference/iot/list-violation-events.html)
## ML Detect APIs
The following APIs can be used to create and manage ML Detect Security Profiles.
+ [CreateSecurityProfile](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateSecurityProfile.html)
+ [AttachSecurityProfile](https://docs.aws.amazon.com/iot/latest/apireference/API_AttachSecurityProfile.html)
+ [ListSecurityProfiles](https://docs.aws.amazon.com/iot/latest/apireference/API_ListSecurityProfiles.html)
+ [DescribeSecurityProfile](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeSecurityProfile.html)
+ [UpdateSecurityProfile](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateSecurityProfile.html)
+ [DeleteSecurityProfile](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteSecurityProfile.html)
+ [GetBehaviorModelTrainingSummaries](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBehaviorModelTrainingSummaries.html)
+ [ListActiveViolations](https://docs.aws.amazon.com/iot/latest/apireference/API_ListActiveViolations.html)
+ [ListViolationEvents](https://docs.aws.amazon.com/iot/latest/apireference/API_ListViolationEvents.html)
+ [PutVerificationStateOnViolation](https://docs.aws.amazon.com/iot/latest/apireference/API_PutVerificationStateOnViolation.html)
## Pause or delete an ML Detect Security Profile
You can pause your ML Detect Security Profile to stop monitoring device behaviors temporarily, or delete your ML Detect Security Profile to stop monitoring device behaviors for an extended period of time.
**Pause ML Detect Security Profile by using the console**
To pause an ML Detect Security Profile using the console, you must first have an empty thing group. To create an empty thing group, see [Static thing groups](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html) in the *AWS IoT Core Developer Guide*. If you have created an empty thing group, then set the empty thing group as the target of the ML Detect Security Profile.
You need to set the target of your Security Profile back to a device group with devices within 30 days, or you won't be able to reactivate the Security Profile.
**Delete ML Detect Security Profile by using the console**
To delete a Security Profile, follow these steps:
1. In the AWS IoT console navigate to the sidebar and choose the **Defend** section.
1. Under **Defend**, choose **Detect** and then **Security Profiles**.
1. Choose the ML Detect Security Profile you want to delete.
1. Choose **Actions**, and then from the options, choose **Delete**.
After an ML Detect Security Profile is deleted, you won’t be able to reactivate the Security Profile.
**Pause an ML Detect Security Profile by using the CLI**
To pause a ML Detect Security Profile by using the CLI, use the `detach-security-security-profile` command:
```
$aws iot detach-security-profile --security-profile-name SecurityProfileName --security-profile-target-arn arn:aws:iot:us-east-1:123456789012:all/registered-things
```
This option is only available in AWS CLI. Similar to the console workflow, you need to set the target of your Security Profile back to a device group with devices within 30 days, or you won't be able to reactivate the Security Profile. To attach a Security Profile to a device group, use the [https://docs.aws.amazon.com/cli/latest/reference/iot/attach-security-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iot/attach-security-profile.html) command.
**Delete a ML Detect Security Profile by using the CLI**
You can delete a Security Profile by using the `delete-security-profile` command below:
```
delete-security-profile --security-profile-name SecurityProfileName
```
After an ML Detect Security Profile is deleted, you won’t be able to reactivate the Security Profile.
# Custom metrics
With AWS IoT Device Defender custom metrics, you can define and monitor metrics that are unique to your fleet or use case, such as number of devices connected to Wi-Fi gateways, charge levels for batteries, or number of power cycles for smart plugs. Custom metric behaviors are defined in Security Profiles, which specify expected behaviors for a group of devices (a thing group) or for all devices. You can monitor behaviors by setting up alarms, which you can use to detect and respond to issues that are specific to the devices.
**Topics**
+ [How to use custom metrics in the console](#dd-detect-custom-metrics-how-to-console)
+ [How to use custom metrics from the CLI](#dd-detect-custom-metrics-how-to-cli)
+ [Custom metrics CLI commands](#dd-detect-custom-metrics-cli-commands)
+ [Custom metrics APIs](#dd-detect-custom-metrics-apis)
## How to use custom metrics in the console
**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detect-custom-metrics-device-agent)
+ [Create a custom metric and add it to a Security Profile](#dd-detect-console-create)
+ [View custom metric details](#dd-detect-console-read)
+ [Update a custom metric](#dd-detect-console-edit)
+ [Delete a custom metric](#dd-detect-console-delete)
### AWS IoT Device Defender Agent SDK (Python)
To get started, download the AWS IoT Device Defender Agent SDK (Python) sample agent. The agent gathers the metrics and publishes reports. Once your device-side metrics are publishing, you can view the metrics being collected and determine thresholds for setting up alarms. Instructions for setting up the device agent are available on the [AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). For more information, see [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).
### Create a custom metric and add it to a Security Profile
The following procedure shows you how to create a custom metric in the console.
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Metrics**.
1. On the **Custom metrics** page, choose **Create**.
1. On the **Create custom metric** page, do the following.
1. Under **Name**, enter a name for your custom metric. You can't modify this name after you create the custom metric.
1. Under **Display name (optional)**, you can enter a friendly name for your custom metric. It doesn't have to be unique and it can be modified after creation.
1. Under **Type**, choose the type of metric you'd like to monitor. Metric types include **string-list**, **ip-address-list**, **number-list**, and **number**. The type can't be modified after creation.
**Note**
ML Detect only allows the **number** type.
1. Under **Tags**, you can select tags to be associated with the resource.
When you're done, choose **Confirm**.
1. After you've created your custom metric, the **Custom metrics** page appears, where you can see your newly created custom metric.
1. Next, you need to add your custom metric to a Security Profile. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Security profiles**.
1. Choose the Security Profile you'd like to add your custom metric to.
1. Choose **Actions**, **Edit**.
1. Choose **Additional Metrics to retain**, and then choose your custom metric. Choose **Next** on the following screens until you reach the **Confirm** page. Choose **Save** and **Continue**. After your custom metric has been successfully added, the Security Profile details page appears.
**Note**
Percentile statistics are not available for metrics when any of the metric values are negative numbers.
### View custom metric details
The following procedure shows you how to view a custom metric's details in the console.
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Metrics**.
1. Choose the **Metric name** of the custom metric you'd like to view the details of.
### Update a custom metric
The following procedure shows you how to update a custom metric in the console.
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Metrics**.
1. Choose the option button next to the custom metric you'd like to update. Then, for **Actions**, choose **Edit**.
1. On the **Update custom metric** page, you can edit the display name and remove or add tags.
1. After you're done, choose **Update**. The **Custom metrics** page.
### Delete a custom metric
The following procedure shows you how to delete a custom metric in the console.
1. First, remove your custom metric from any Security Profile it's referenced in. You can view which Security Profiles contain your custom metric on your custom metric details page. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Metrics**.
1. Choose the custom metric you'd like to remove. Remove the custom metric from any Security Profile listed under **Security Profiles** on the custom metric details page.
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Metrics**.
1. Choose the option button next to the custom metric you'd like to delete. Then, for **Actions**, choose **Delete**.
1. On the **Are you sure you want to delete custom metric?** message, choose **Delete custom metric**.
**Warning**
After you've deleted a custom metric, you lose all data associated with the metric. This action can't be undone.
## How to use custom metrics from the CLI
**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detec-custom-metrics-cli-sdk)
+ [Create a custom metric and add it to a Security Profile](#dd-detect-custom-cli-create)
+ [View custom metric details](#dd-detect-custom-cli-read)
+ [Update a custom metric](#dd-detect-custom-cli-edit)
+ [Delete a custom metric](#dd-detect-custom-cli-delete)
### AWS IoT Device Defender Agent SDK (Python)
To get started, download the AWS IoT Device Defender Agent SDK (Python) sample agent. The agent gathers the metrics and publishes reports. After your device-side metrics are publishing, you can view the metrics being collected and determine thresholds for setting up alarms. Instructions for setting up the device agent are available on the [AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). For more information, see [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).
### Create a custom metric and add it to a Security Profile
The following procedure shows you how to create a custom metric and add it to a Security Profile from the CLI.
1. Use the `[create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)` command to create your custom metric. The following example creates a custom metric that measures battery percentage.
```
aws iot create-custom-metric \
--metric-name "batteryPercentage" \
--metric-type "number" \
--display-name "Remaining battery percentage." \
--region us-east-1
--client-request-token "02ccb92b-33e8-4dfa-a0c1-35b181ed26b0" \
```
Output:
```
{
"metricName": "batteryPercentage",
"metricArn": "arn:aws:iot:us-east-1:1234564789012:custommetric/batteryPercentage"
}
```
1. After you've created your custom metric, you can either add the custom metric to an existing profile using `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)` or create a new security profile to add the custom metric to using `[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)`. Here, we create a new security profile called *batteryUsage* to add our new *batteryPercentage* custom metric to. We also add a Rules Detect metric called *cellularBandwidth*.
```
aws iot create-security-profile \
--security-profile-name batteryUsage \
--security-profile-description "Shows how much battery is left in percentile." \
--behaviors "[{\"name\":\"great-than-75\",\"metric\":\"batteryPercentage\",\"criteria\":{\"comparisonOperator\":\"greater-than\",\"value\":{\"number\":75},\"consecutiveDatapointsToAlarm\":5,\"consecutiveDatapointsToClear\":1}},{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]" \
--region us-east-1
```
Output:
```
{
"securityProfileArn": "arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage",
"securityProfileName": "batteryUsage"
}
```
**Note**
Percentile statistics are not available for metrics when any of the metric values are negative numbers.
### View custom metric details
The following procedure shows you how to view the details for a custom metric from the CLI.
+ Use the `[list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)` command to view all of your custom metrics.
```
aws iot list-custom-metrics \
--region us-east-1
```
The output of this command looks like the following.
```
{
"metricNames": [
"batteryPercentage"
]
}
```
### Update a custom metric
The following procedure shows you how to update a custom metric from the CLI.
+ Use the `[update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)` command to update a custom metric. The following example updates the `display-name`.
```
aws iot update-custom-metric \
--metric-name batteryPercentage \
--display-name 'remaining battery percentage on device' \
--region us-east-1
```
The output of this command looks like the following.
```
{
"metricName": "batteryPercentage",
"metricArn": "arn:aws:iot:us-east-1:1234564789012:custommetric/batteryPercentage",
"metricType": "number",
"displayName": "remaining battery percentage on device",
"creationDate": "2020-11-17T23:01:35.110000-08:00",
"lastModifiedDate": "2020-11-17T23:02:12.879000-08:00"
}
```
### Delete a custom metric
The following procedure shows you how to delete a custom metric from the CLI.
1. To delete a custom metric, first remove it from any Security Profiles that it's attached to. Use the `[list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)` command to view Security Profiles with a certain custom metric.
1. To remove a custom metric from a Security Profile, use the `[update-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profiles.html)` command. Enter all information that you want to keep, but exclude the custom metric.
```
aws iot update-security-profile \
--security-profile-name batteryUsage \
--behaviors "[{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]"
```
The output of this command looks like the following.
```
{
"behaviors": [{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}],
"securityProfileName": "batteryUsage",
"lastModifiedDate": 2020-11-17T23:02:12.879000-09:00,
"securityProfileDescription": "Shows how much battery is left in percentile.",
"version": 2,
"securityProfileArn": "arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage",
"creationDate": 2020-11-17T23:02:12.879000-09:00
}
```
1. After the custom metric is detached, use the `[delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)` command to delete the custom metric.
```
aws iot delete-custom-metric \
--metric-name batteryPercentage \
--region us-east-1
```
The output of this command looks like the following
```
HTTP 200
```
## Custom metrics CLI commands
You can use the following CLI commands to create and manage custom metrics.
+ [create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)
+ [describe-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-custom-metric.html)
+ [list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)
+ [update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)
+ [delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)
+ [list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)
## Custom metrics APIs
The following APIs can be used to create and manage custom metrics.
+ [CreateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCustomMetric.html)
+ [DescribeCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeCustomMetric.html)
+ [ListCustomMetrics](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCustomMetrics.html)
+ [UpdateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCustomMetric.html)
+ [DeleteCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCustomMetric.html)
+ [ListSecurityProfiles](https://docs.aws.amazon.com/iot/latest/apireference/API_ListSecurityProfiles.html)
# Device-side metrics
When creating a Security Profile, you can specify your IoT device's expected behavior by configuring behaviors and thresholds for metrics generated by IoT devices. The following are device-side metrics, which are metrics from agents that you install on your devices.
## Bytes out (`aws:all-bytes-out`)
The number of outbound bytes from a device during a given time period.
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.
Compatible with: Rules Detect \$1 ML Detect
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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-equals",
"value": {
"count": 4096
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "TCP outbound traffic",
"metric": "aws:all-bytes-out",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p50"
},
"durationSeconds": 900,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Outbound traffic ML behavior",
"metric": "aws:all-bytes-out",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Bytes in (`aws:all-bytes-in`)
The number of inbound bytes to a device during a given time period.
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.
Compatible with: Rules Detect \$1 ML Detect
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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-equals",
"value": {
"count": 4096
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "TCP inbound traffic",
"metric": "aws:all-bytes-in",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p90"
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Inbound traffic ML behavior",
"metric": "aws:all-bytes-in",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Listening TCP port count (`aws:num-listening-tcp-ports`)
The number of TCP ports the device is listening on.
Use this metric to specify the maximum number of TCP ports that each device should monitor.
Compatible with: Rules Detect \$1 ML Detect
Unit: failures
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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": "Max TCP Ports",
"metric": "aws:num-listening-tcp-ports",
"criteria": {
"comparisonOperator": "less-than-equals",
"value": {
"count": 5
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "Max TCP Ports",
"metric": "aws:num-listening-tcp-ports",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p50"
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML detect**
```
{
"name": "Max TCP Port ML behavior",
"metric": "aws:num-listening-tcp-ports",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Listening UDP port count (`aws:num-listening-udp-ports`)
The number of UDP ports the device is listening on.
Use this metric to specify the maximum number of UDP ports that each device should monitor.
Compatible with: Rules Detect \$1 ML Detect
Unit: failures
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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": "Max UDP Ports",
"metric": "aws:num-listening-udp-ports",
"criteria": {
"comparisonOperator": "less-than-equals",
"value": {
"count": 5
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "Max UDP Ports",
"metric": "aws:num-listening-udp-ports",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p50"
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Max UPD Port ML behavior",
"metric": "aws:num-listening-tcp-ports",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Packets out (`aws:all-packets-out`)
The number of outbound packets from a device during a given time period.
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.
Compatible with: Rules Detect \$1 ML Detect
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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-equals",
"value": {
"count": 100
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "TCP outbound traffic",
"metric": "aws:all-packets-out",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p90"
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Outbound sent ML behavior",
"metric": "aws:all-packets-out",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Packets in (`aws:all-packets-in`)
The number of inbound packets to a device during a given time period.
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.
Compatible with: Rule Detect \$1 ML Detect
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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-equals",
"value": {
"count": 100
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example**
Example using a `statisticalThreshold`
```
{
"name": "TCP inbound traffic",
"metric": "aws:all-packets-in",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p90"
},
"durationSeconds": 300,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Inbound sent ML behavior",
"metric": "aws:all-packets-in",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## Destination IPs (`aws:destination-ip-addresses`)
A set of IP destinations.
Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as blacklisted) Classless Inter-Domain Routings (CIDR) from which each device must or must not connect to AWS IoT.
Compatible with: Rules Detect
Operators: in-cidr-set \$1 not-in-cidr-set
Values: a list of CIDRs
Units: n/a
**Example**
```
{
"name": "Denied source IPs",
"metric": "aws:destination-ip-address",
"criteria": {
"comparisonOperator": "not-in-cidr-set",
"value": {
"cidrs": [ "12.8.0.0/16", "15.102.16.0/24" ]
}
},
"suppressAlerts": true
}
```
## Listening TCP ports (`aws:listening-tcp-ports`)
The TCP ports that the device is listening on.
Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as blacklisted) TCP ports on which each device must or must not listen.
Compatible with: Rules Detect
Operators: in-port-set \$1 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 ]
}
},
"suppressAlerts": true
}
```
## Listening UDP ports (`aws:listening-udp-ports`)
The UDP ports that the device is listening on.
Use this metric to specify a set of allowed (formerly referred to as whitelisted) or denied (formerly referred to as blacklisted) UDP ports on which each device must or must not listen.
Compatible with: Rules Detect
Operators: in-port-set \$1 not-in-port-set
Values: a list of ports
Units: n/a
**Example**
```
{
"name": "Listening UDP Ports",
"metric": "aws:listening-udp-ports",
"criteria": {
"comparisonOperator": "in-port-set",
"value": {
"ports": [ 1025, 2000 ]
}
}
}
```
## Established TCP connections count (`aws:num-established-tcp-connections`)
The number of TCP connections for a device.
Use this metric to specify the maximum or minimum number of active TCP connections that each device should have (All TCP states).
Compatible with: Rules Detect \$1 ML Detect
Operators: less-than \$1 less-than-equals \$1 greater-than \$1 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-equals",
"value": {
"count": 3
},
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using a `statisticalThreshold`**
```
{
"name": "TCP Connection Count",
"metric": "aws:num-established-tcp-connections",
"criteria": {
"comparisonOperator": "less-than-equals",
"statisticalThreshold": {
"statistic": "p90"
},
"durationSeconds": 900,
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1
},
"suppressAlerts": true
}
```
**Example using ML Detect**
```
{
"name": "Connection count ML behavior",
"metric": "aws:num-established-tcp-connections",
"criteria": {
"consecutiveDatapointsToAlarm": 1,
"consecutiveDatapointsToClear": 1,
"mlDetectionConfig": {
"confidenceLevel": "HIGH"
}
},
"suppressAlerts": true
}
```
## 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 | | A report can have both or at least one `metrics` or `custom_metrics` block. |
| custom\$1metrics | cmet | Y | Object | | A report can have both or at least one `metrics` or `custom_metrics` block. |
**Header block**
| Long name | Short name | Required | Type | Constraints | Notes |
| --- | --- | --- | --- | --- | --- |
| report\$1id | 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\$1connections | tc | metrics | N | Object | | |
| established\$1connections | ec | tcp\$1connections | N | Object | | Established TCP state |
| connections | cs | established\$1connections | N | List