# Getting started with AWS IoT Device Defender Getting started with AWS IoT Device Defender You can use the following tutorials to work with AWS IoT Device Defender. **Topics** + [ # Setting up ](dd-setting-up.md) + [ # Audit guide ](audit-tutorial.md) + [ # ML Detect guide ](dd-detect-ml-getting-started.md) + [ # Customize when and how you view AWS IoT Device Defender audit results ](dd-suppressions-example.md) # Setting up Before you use AWS IoT Device Defender for the first time, complete the following tasks: **Topics** + [ ## Sign up for an AWS account ](#sign-up-for-aws) + [ ## Create a user with administrative access ](#create-an-admin) ## Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. ## Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. These tasks create an AWS account and a user with administrator privileges for the account. # Audit guide Audit guide This tutorial provides instructions on how to configure a recurring audit, setting up alarms, reviewing audit results and mitigating audit issues. **Topics** + [ ## Prerequisites ](#audit-tutorial-prerequisites) + [ ## Enable audit checks ](#audit-tutorial-enable-checks) + [ ## View audit results ](#audit-tutorial-view-audit) + [ ## Creating audit mitigation actions ](#audit-tutorial-mitigation) + [ ## Apply mitigation actions to your audit findings ](#apply-mitigation-actions) + [ ## Creating an AWS IoT Device Defender Audit IAM role (optional) ](#audit-iam) + [ ## Enable SNS notifications (optional) ](#audit-tutorial-enable-sns) + [ ## Configure permissions for customer managed keys (optional) ](#audit-tutorial-cmk-permissions) + [ ## Enable logging (optional) ](#enable-logging) ## Prerequisites To complete this tutorial, you need the following: + An AWS account. If you don't have this, see [Setting up](https://docs.aws.amazon.com/iot/latest/developerguide/dd-setting-up.html). ## Enable audit checks In the following procedure, you enable audit checks that look at account and device settings and policies to ensure security measures are in place. In this tutorial we instruct you to enable all audit checks, but you're able to select whichever checks you wish. Audit pricing is per device count per month (fleet devices connected to AWS IoT). Therefore, adding or removing audit checks would not affect your monthly bill when using this feature. 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). In the navigation pane, expand **Security** and choose **Intro**. 1. Choose **Automate AWS IoT security audit**. Audit checks are automatically turned on. 1. Expand **Audit** and choose **Settings** to view your audit checks. Select an audit check name to learn about what the audit check does. For more information about audit checks, see [Audit Checks](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-audit-checks.html). 1. (Optional) If you already have a role that you want to use, choose **Manage service permissions**, choose the role from the list, and then choose **Update**. ## View audit results The following procedure shows you how to view your audit results. In this tutorial, you see the audit results from the audit checks set up in [Enable audit checks](#audit-tutorial-enable-checks) tutorial. **To view audit results** 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). In the navigation pane, expand **Security**, **Audit**, and then choose **Results**. 1. Select the **Name** of the audit schedule you'd like to investigate. 1. In **Non-compliant checks**, under **Mitigation**, select the info buttons for information about why it's non-compliant. For guidance on how to make your non-compliant checks compliant, see [Audit checks](device-defender-audit-checks.md). ## Creating audit mitigation actions In the following procedure, you will create an AWS IoT Device Defender Audit Mitigation Action to enable AWS IoT logging. Each audit check has mapped mitigation actions that will affect which **Action type** you choose for the audit check you want to fix. For more information, see [Mitigation actions](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-mitigation-actions.html#defender-audit-apply-mitigation-actions.html). **To use the AWS IoT console to create mitigation actions** 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). In the navigation pane, expand **Security**, **Detect**, and then choose **Mitigation actions**. 1. On the **Mitigation actions** page, choose **Create**. 1. On the **Create a new mitigation action** page, for **Action name**, enter a unique name for your mitigation action such as *EnableErrorLoggingAction*. 1. For **Action type**, choose **Enable AWS IoT logging**. 1. In **Permissions**, choose **Create role**. For **Role name**, use *IoTMitigationActionErrorLoggingRole*. Then, choose **Create**. 1. In **Parameters**, under **Role for logging**, choose `IoTMitigationActionErrorLoggingRole`. For **Log level**, choose `Error`. 1. Choose **Create**. ## Apply mitigation actions to your audit findings The following procedure shows you how to apply mitigation actions to your audit results. **To mitigate non-compliant audit findings** 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). In the navigation pane, expand **Security**, **Audit**, and then choose **Results**. 1. Choose an audit result that you want to respond to. 1. Check your results. 1. Choose **Start mitigation actions**. 1. For **Logging disabled**, choose the mitigation action that you previously created, `EnableErrorLoggingAction`. You can select the appropriate actions for each non-compliant finding to address the issues. 1. For **Select reason codes**, choose the reason code that was returned by the audit check. 1. Choose **Start task**. The mitigation action may take a few minutes to run. **To check that the mitigation action worked** 1. In the AWS IoT console, in the navigation pane, choose **Settings**. 1. In **Service log**, confirm that the **Log level** is `Error (least verbosity)`. ## Creating an AWS IoT Device Defender Audit IAM role (optional) In the following procedure, you create an AWS IoT Device Defender Audit IAM role that provides AWS IoT Device Defender read access to AWS IoT. **To create the service role for AWS IoT Device Defender (IAM console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**. 1. Choose the **AWS service** role type. 1. In **Use cases for other AWS services**, choose **AWS IoT**, and then choose **IoT - Device Defender Audit**. 1. Choose **Next**. 1. (Optional) Set a [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html). This is an advanced feature that is available for service roles, but not service-linked roles. Expand the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions boundary or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. After you create the policy, close that tab and return to your original tab to select the policy to use for the permissions boundary. 1. Choose **Next**. 1. Enter a role name to help you identify the purpose of this role. Role names must be unique within your AWS account. They are not distinguished by case. For example, you cannot create roles named both **PRODROLE** and **prodrole**. Because various entities might reference the role, you can't edit the name of the role after it has been created. 1. (Optional) For **Description**, enter a description for the new role. 1. Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Select permissions** sections to edit the use cases and permissions for the role. 1. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*. 1. Review the role and then choose **Create role**. ## Enable SNS notifications (optional) In the following procedure, you enable Amazon SNS (SNS) notifications to alert you when your audits identify any non-compliant resources. In this tutorial you will set up notifications for the audit checks enabled in the [Enable audit checks](#audit-tutorial-enable-checks) tutorial. 1. If you haven't already, attach a policy that provides access to SNS via the AWS Management Console. You can do this by following the instructions in [Attaching a policy to an IAM user group](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_manage_attach-policy.html) in the *IAM User Guide* and selecting the **AWSIoTDeviceDefenderPublishFindingsToSNSMitigationAction** policy. 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). In the navigation pane, expand **Security**, **Audit**, and then choose **Settings**. 1. At the bottom of the **Device Defender audit settings** page, choose **Enable SNS alerts**. 1. Choose **Enabled**. 1. For **Topic**, choose **Create new topic**. Name the topic *IoTDDNotifications* and choose **Create**. For **Role**, choose the role that you created in [Creating an AWS IoT Device Defender Audit IAM role (optional)](#audit-iam). 1. Choose **Update**. 1. If you'd like to receive email or text in your Ops platforms through Amazon SNS, see [Using Amazon Simple Notification Service for user notifications](https://docs.aws.amazon.com/sns/latest/dg/sns-user-notifications.html). ## Configure permissions for customer managed keys (optional) **Note** This configuration is only required if you have opted in to customer managed keys for AWS IoT Core. For more information about AWS IoT Core encryption at rest, see [Data encryption at rest in AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/encryption-at-rest.html). If you have enabled customer managed keys (CMK) for AWS IoT Core encryption at rest, the IAM role used by AWS IoT Device Defender Audit requires additional permissions to decrypt data. Without these permissions, audit operations will fail. The [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSIoTDeviceDefenderAudit.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSIoTDeviceDefenderAudit.html) managed policy does not include `kms:Decrypt` permissions by design, following the principle of least privilege. You must manually add these permissions to your audit role when using customer managed keys. **To add KMS permissions to your AWS IoT Device Defender Audit IAM role** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**, and then search for the role you created in [Creating an AWS IoT Device Defender Audit IAM role (optional)](#audit-iam) or the role you specified when configuring audit settings. 1. Choose the role name to open its details page. 1. In the **Permissions** tab, choose **Add permissions**, and then choose **Create inline policy**. 1. Choose the **JSON** tab and enter the following policy. Replace *REGION*, *ACCOUNT\$1ID*, and *KEY\$1ID* with your AWS KMS key details: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID" } ] } ``` 1. Choose **Next**. 1. For **Policy name**, enter a descriptive name such as **DeviceDefenderAuditKMSDecrypt**. 1. Choose **Create policy**. ## Enable logging (optional) This procedure describes how to enable AWS IoT to log information to CloudWatch Logs. This will allow you to view your audit results. Enabling logging may result in incurred charges. **To enable logging** 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). On the navigation pane, choose **Settings**. 1. In **Logs**, choose **Manage logs**. 1. For **Select role**, choose **Create role**. Name the role *AWSIoTLoggingRole* and choose **Create**. A policy is automatically attached. 1. For **Log level**, choose **Debug (most verbosity)**. 1. Choose **Update**. # ML Detect guide **Note** ML Detect is not available in the following regions: Asia Pacific (Malaysia) In this Getting Started guide, you create an ML Detect Security Profile that uses machine learning (ML) to create models of expected behavior based on historical metric data from your devices. While ML Detect is creating the ML model, you can monitor its progress. After the ML model is built, you can view and investigate alarms on an ongoing basis and mitigate identified issues. For more information about ML Detect and its API and CLI commands, see [ML Detect](dd-detect-ml.md). **Topics** + [ ## Prerequisites ](#ml-detect-prereqs) + [ ## How to use ML Detect in the console ](#dd-detect-ml-console) + [ ## How to use ML Detect with the CLI ](#dd-detect-ml-cli) ## Prerequisites + An AWS account. If you don't have this, see [Setting up](https://docs.aws.amazon.com/iot/latest/developerguide/dd-setting-up.html). ## How to use ML Detect in the console **Topics** + [ ### Enable ML Detect ](#enable-ml-detect-console) + [ ### Monitor your ML model status ](#monitor-ml-models-console) + [ ### Review your ML Detect alarms ](#review-ml-alarms-console) + [ ### Fine-tune your ML alarms ](#fine-tune-ml-models-console) + [ ### Mark your alarm's verification state ](#mark-your-alarms) + [ ### Mitigate identified device issues ](#mitigate-ml-issues-console) ### Enable ML Detect The following procedures detail how to set up ML Detect in the console. 1. First, make sure your devices will create the minimum datapoints required as defined in [ML Detect minimum requirements](dd-detect-ml.md#dd-detect-ml-requirements) for ongoing training and refreshing of the model. For data collection to progress, ensure your Security Profile is attached to a target, which can be a thing or thing group. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**. Choose **Detect**, **Security profiles**, **Create security profile**, and then **Create ML anomaly Detect profile**. 1. On the **Set basic configurations** page, do the following. + Under **Target**, choose your target device groups. + Under **Security profile name**, enter a name for your Security Profile. + (Optional) Under **Description** you can write in a short description for the ML profile. + Under **Selected metric behaviors in Security Profile**, choose the metrics you'd like to monitor. ![\[Create ML Security Profile configuration page with all registered things selected as target, metric behaviors listed such as authorization failures and connection attempts, and options to add cloud- or device-side metrics.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-set-basic.png) When you're done, choose **Next**. 1. On the **Set SNS (optional)** page, specify an SNS topic for alarm notifications when a device violates a behavior in your profile. Choose an IAM role you will use to publish to the selected SNS topic. If you don't have an SNS role yet, use the following steps to create a role with the proper permissions and trust relationships required. + Navigate to the [IAM console](https://console.aws.amazon.com/iam/). In the navigation pane, choose **Roles** and then choose **Create role**. + Under **Select type of trusted entity**, select **AWS Service**. Then, under **Choose a use case**, choose **IoT** and under **Select your use case**, choose **IoT - Device Defender Mitigation Actions**. When you're done, choose **Next: Permissions**. + Under **Attached permissions policies**, ensure that **AWSIoTDeviceDefenderPublishFindingsToSNSMitigationAction** is selected, and then choose **Next: Tags**. ![\[Permissions policies table for an AWS IoT Device Defender role with policy names, descriptions of what each policy provides access for, and options to filter or search policies.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-sns-findings.png) + Under **Add tags (optional)**, you can add any tags you'd like to associate with your role. When you're done, choose **Next: Review**. + Under **Review**, give your role a name and ensure that **AWSIoTDeviceDefenderPublishFindingsToSNSMitigationAction** is listed under **Permissions** and **AWS service: iot.amazonaws.com** is listed under **Trust relationships**. When you're done, choose **Create role**. ![\[IAM roles summary page showing Sample-SNS-role details like role ARN, description, instance profile ARNs, path, creation time, maximum session duration, and applied AWS IoT Device Defender publish findings to SNS mitigation action policy\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-detect-permissions.png) ![\[IAM Sample-SNS-role summary showing role ARN, role description providing AWS IoT Device Defender write access to publish SNS notifications, path, creation time, and trusted entities\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-detect-trust-relationships.png) 1. On the **Edit Metric behavior** page, you can customize your ML behavior settings. ![\[Edit metric behaviors section with Authorization failures, Bytes in, and Connection attempts metrics, allowing configuration of data points for alarm triggers, notifications, and ML Detect confidence levels.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-update-config.png) 1. When you're done, choose **Next**. 1. On the **Review configuration** page, verify the behaviors you'd like machine learning to monitor, and then choose **Next**. ![\[Edit ML Security Profile page showing Smart_lights_ML_Detect_Security_Profile targeting all registered things, with metric behaviors for authorization failures, bytes out, connection attempts, and disconnects.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-review-config.png) 1. After you've created your Security Profile, you're redirected to the **Security Profiles** page, where the newly created Security Profile appears. **Note** The initial ML model training and creation takes 14 days to complete. You can expect to see alarms after it's complete, if there is any anomalous activity on your devices. ### Monitor your ML model status While your ML models are in the initial training period, you can monitor their progress at any time by taking the following steps. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Security profiles**. 1. On the **Security Profiles** page, choose the Security Profile you'd like to review. Then, choose **Behaviors and ML training**. 1. On the **Behaviors and ML training** page, check the training progress of your ML models. After your model status is **Active**, it'll start making Detect decisions based on your usage and update the profile every day. ![\[Dashboard showing low confidence machine learning models for monitoring TCP/UDP listening ports and established TCP connections.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-active-state.png) **Note** If your model doesn't progress as expected, make sure your devices are meeting the [Minimum requirements](dd-detect-ml.md#dd-detect-ml-requirements). ### Review your ML Detect alarms After your ML models are built and ready for data inference, you can regularly view and investigate alarms that are identified by the models. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Alarms**. ![\[AWS IoT Device Defender alarms list showing 5 active authorization failure alarms with Thing names, Security Profile, behavior type, behavior name, last emitted time, and verification state columns.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-alarms.png) 1. If you navigate to the **History** tab, you can also view details about your devices that are no longer in alarms. ![\[Line graph showing alarms in alarm, cleared, and invalidated over a two-week period, with number of alarms on the y-axis and dates on the x-axis.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-history-alarm.png) To get more information, under **Manage** choose **Things**, chose the thing you'd like to see more details for, and then navigate to **Defender metrics**. You can access the **Defender metrics graph** and perform your investigation on anything in alarm from the **Active** tab. In this case, the graph shows a spike in message size, which initiated the alarm. You can see the alarm subsequently cleared. ![\[IoT thing dashboard showing message size maximum metric graph with peak at 801 bytes on specified date and time.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-defender-metrics.png) ### Fine-tune your ML alarms After your ML models are built and ready for data evaluations, you can update your Security Profile's ML behavior settings to change the configuration. The following procedure shows you how to update your Security Profile's ML behavior settings in the AWS CLI. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Detect**, **Security profiles**. 1. On the **Security Profiles** page, select the check box next to the Security Profile you'd like to review. Then, choose **Actions**, **Edit**. ![\[AWS IoT Device Defender Security Profiles list showing profile name, ML threshold type, behaviors retained, target things, creation date, notifications status\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-fine-tune.png) 1. Under **Set basic configurations**, you can adjust Security Profile target thing groups or change what metrics you want to monitor. ![\[Create ML Security Profile configuration page with all registered things selected as target, metric behaviors listed such as authorization failures and connection attempts, and options to add cloud- or device-side metrics\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-set-basic.png) 1. You can update any of the following by navigating to **Edit metric behaviors**. + Your ML model datapoints required to initiate alarm + Your ML model datapoints required to clear alarm + Your ML Detect confidence level + Your ML Detect notifications (for example, **Not suppressed**, **Suppressed**) ![\[Edit metric behaviors section with options to configure authorization failures, bytes out, and connection attempts metrics for ML security profile.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-update-config-2.png) ### Mark your alarm's verification state Mark your alarms by setting the verification state and providing a description of that verification state. This helps you and your team identify alarms that you don't have to respond to. 1. In the [AWS IoT console](https://console.aws.amazon.com/iot/), on the navigation pane, expand **Defend**, and then choose **Detect**, **Alarms**. Select an alarm to mark its verification state. ![\[AWS IoT Device Defender Alarms view showing active authorization failure behavior events for IoT console things such as iotconsole-6f8379bc-c245-4ffe-8ef7-b2b52e78975c with fdsa security profile.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-alarm-select.png) 1. Choose **Mark verification state**. The verification state modal opens. 1. Choose the appropriate verification state, enter a verification description (optional), and then choose **Mark**. This action assigns a verification state and description to the chosen alarm. ![\[Dialog to mark alarm verification state with options: Unknown, True positive, False positive, Benign positive.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-alarm-state-window.png) ### Mitigate identified device issues 1. *(Optional)* Before setting up quarantine mitigation actions, let's set up a quarantine group where we'll move the device that's in violation to. You can also use an existing group. 1. Navigate to **Manage**, **Thing groups**, and then **Create Thing Group**. Name your thing group. For this tutorial, we'll name our thing group `Quarantine_group`. Under **Thing group**, **Security**, apply the following policy to the thing group. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "iot:*", "Resource": "*" } ] } ``` ------ ![\[AWS IoT console Create Thing Group page with Create Thing Group button.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-create-thing-group.png) When you're done, choose **Create thing group**. 1. Now that we've created a thing group, let's create a mitigation action that move devices that in alarm into the `Quarantine_group`. Under **Defend**, **Mitigation actions**, choose **Create**. ![\[AWS IoT Device Defender mitigation action configuration form with Action name, Action type, Permissions, Action execution role, and Thing groups fields.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-miti-create.png) 1. On the **Create a new mitigation action** page, enter the following information. + **Action name**: Give your mitigation action a name, such as **Quarantine\$1action**. + **Action type**: Choose the type of action. We'll choose **Add things to thing group (Audit or Detect mitigation)**. + **Action execution role**: Create a role or choose an existing role if you created one earlier. + **Parameters**: Choose a thing group. We can use `Quarantine_group`, which we created earlier. ![\[AWS IoT Device Defender mitigation action configuration form with Action name, Action type, Permissions, Action execution role, and Thing groups fields.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-miti-create-form.png) When you're done, choose **Save**. You now have a mitigation action that moves devices in alarm to a quarantine thing group, and a mitigation action to isolate the device while you investigate. 1. Navigate to **Defender**, **Detect**, **Alarms**. You can see which devices are in alarm state under **Active**. ![\[AWS IoT Device Defender alarms list showing 5 active authorization failure alarms with Thing names, Security Profile, behavior type, behavior name, last emitted time, and verification state columns.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-alarms.png) Select the device you want to move to the quarantine group and choose **Start Mitigation Actions**. 1. Under **Start mitigation actions**, **Start Actions** select the mitigation action you created earlier. For example, we'll choose **Quarantine\$1action**, then choose **Start**. The Action Tasks page opens. ![\[Mitigation actions dialog with "udml7" listed as the affected thing, checkbox to confirm irreversible actions, and dropdown to choose action(s) to execute.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-start-action.png) 1. The device is now isolated in **Quarantine\$1group** and you can investigate the root cause of the issue that set off the alarm. After you complete the investigation, you can move the device out of the thing group or take further actions. ![\[AWS IoT Device Defender Detect Action tasks table showing one quarantine action to add things to quarantine_group thing group.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-ml-action-tasks.png) ## How to use ML Detect with the CLI The following shows you how to set up ML Detect using the CLI. **Topics** + [ ### Enable ML Detect ](#enable-ml-detect-cli) + [ ### Monitor your ML model status ](#monitor-ml-models-cli) + [ ### Review your ML Detect alarms ](#review-ml-alarms-cli) + [ ### Fine-tune your ML alarms ](#fine-tune-ml-models-cli) + [ ### Mark your alarm's verification state ](#mark-verification-state-cli) + [ ### Mitigate identified device issues ](#mitigate-issues-cli) ### Enable ML Detect The following procedure shows you how to enable ML Detect in the AWS CLI. 1. Make sure your devices will create the minimum datapoints required as defined in [ML Detect minimum requirements](dd-detect-ml.md#dd-detect-ml-requirements) for ongoing training and refreshing of the model. For data collection to progress, ensure your things are in a thing group attached to a Security Profile. 1. Create an ML Detect Security Profile by using the `[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)` command. The following example creates a Security Profile named *security-profile-for-smart-lights* that checks for number of messages sent, number of authorization failures, number of connection attempts, and number of disconnects. The example uses `mlDetectionConfig` to establish that the metric will use the ML Detect model. ``` aws iot create-security-profile \ --security-profile-name security-profile-for-smart-lights \ --behaviors \ '[{ "name": "num-messages-sent-ml-behavior", "metric": "aws:num-messages-sent", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }, { "name": "num-authorization-failures-ml-behavior", "metric": "aws:num-authorization-failures", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }, { "name": "num-connection-attempts-ml-behavior", "metric": "aws:num-connection-attempts", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }, { "name": "num-disconnects-ml-behavior", "metric": "aws:num-disconnects", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }]' ``` Output: ``` { "securityProfileName": "security-profile-for-smart-lights", "securityProfileArn": "arn:aws:iot:eu-west-1:123456789012:securityprofile/security-profile-for-smart-lights" } ``` 1. Next, associate your Security Profile with one or multiple thing groups. Use the `[attach-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/attach-security-profile.html)` command to attach a thing group to your Security Profile. The following example associates a thing group named *ML\$1Detect\$1beta\$1static\$1group* with the *security-profile-for-smart-lights* Security Profile. ``` aws iot attach-security-profile \ --security-profile-name security-profile-for-smart-lights \ --security-profile-target-arn arn:aws:iot:eu-west-1:123456789012:thinggroup/ML_Detect_beta_static_group ``` Output: None. 1. After you've created your complete Security Profile, the ML model begins training. The initial ML model training and building takes 14 days to complete. After 14 days, if there's anomalous activity on your device, you can expect to see alarms. ### Monitor your ML model status The following procedure shows you how to monitor your ML models in-progress training. + Use the `[get-behavior-model-training-summaries](https://docs.aws.amazon.com/cli/latest/reference/iot/get-behavior-model-training-summaries.html)` command to view your ML model's progress. The following example gets the ML model training progress summary for the *security-profile-for-smart-lights* Security Profile. `modelStatus` shows you if a model has completed training or is still pending build for a particular behavior. ``` aws iot get-behavior-model-training-summaries \ --security-profile-name security-profile-for-smart-lights ``` Output: ``` { "summaries": [ { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Messages_sent_ML_behavior", "trainingDataCollectionStartDate": "2020-11-30T14:00:00-08:00", "modelStatus": "ACTIVE", "datapointsCollectionPercentage": 29.408, "lastModelRefreshDate": "2020-12-07T14:35:19.237000-08:00" }, { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Messages_received_ML_behavior", "modelStatus": "PENDING_BUILD", "datapointsCollectionPercentage": 0.0 }, { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Authorization_failures_ML_behavior", "trainingDataCollectionStartDate": "2020-11-30T14:00:00-08:00", "modelStatus": "ACTIVE", "datapointsCollectionPercentage": 35.464, "lastModelRefreshDate": "2020-12-07T14:29:44.396000-08:00" }, { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Message_size_ML_behavior", "trainingDataCollectionStartDate": "2020-11-30T14:00:00-08:00", "modelStatus": "ACTIVE", "datapointsCollectionPercentage": 29.332, "lastModelRefreshDate": "2020-12-07T14:30:44.113000-08:00" }, { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Connection_attempts_ML_behavior", "trainingDataCollectionStartDate": "2020-11-30T14:00:00-08:00", "modelStatus": "ACTIVE", "datapointsCollectionPercentage": 32.891999999999996, "lastModelRefreshDate": "2020-12-07T14:29:43.121000-08:00" }, { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "Disconnects_ML_behavior", "trainingDataCollectionStartDate": "2020-11-30T14:00:00-08:00", "modelStatus": "ACTIVE", "datapointsCollectionPercentage": 35.46, "lastModelRefreshDate": "2020-12-07T14:29:55.556000-08:00" } ] } ``` **Note** If your model doesn't progress as expected, make sure your devices are meeting the [Minimum requirements](dd-detect-ml.md#dd-detect-ml-requirements). ### Review your ML Detect alarms After your ML models are built and ready for data evaluations, you can regularly view any alarms that are inferred by the models. The following procedure shows you how to view your alarms in the AWS CLI. + To see all active alarms, use the `[list-active-violations](https://docs.aws.amazon.com/cli/latest/reference/iot/list-active-violations.html)` command. ``` aws iot list-active-violations \ --max-results 2 ``` Output: ``` { "activeViolations": [] } ``` Alternatively, you can view all violations discovered during a given time period by using the `[list-violation-events](https://docs.aws.amazon.com/cli/latest/reference/iot/list-violation-events.html)` command. The following example lists violation events from September 22, 2020 5:42:13 GMT to October 26, 2020 5:42:13 GMT. ``` aws iot list-violation-events \ --start-time 1599500533 \ --end-time 1600796533 \ --max-results 2 ``` Output: ``` { "violationEvents": [ { "violationId": "1448be98c09c3d4ab7cb9b6f3ece65d6", "thingName": "lightbulb-1", "securityProfileName": "security-profile-for-smart-lights", "behavior": { "name": "LowConfidence_MladBehavior_MessagesSent", "metric": "aws:num-messages-sent", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }, "violationEventType": "alarm-invalidated", "violationEventTime": 1600780245.29 }, { "violationId": "df4537569ef23efb1c029a433ae84b52", "thingName": "lightbulb-2", "securityProfileName": "security-profile-for-smart-lights", "behavior": { "name": "LowConfidence_MladBehavior_MessagesSent", "metric": "aws:num-messages-sent", "criteria": { "consecutiveDatapointsToAlarm": 1, "consecutiveDatapointsToClear": 1, "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": true }, "violationEventType": "alarm-invalidated", "violationEventTime": 1600780245.281 } ], "nextToken": "Amo6XIUrsOohsojuIG6TuwSR3X9iUvH2OCksBZg6bed2j21VSnD1uP1pflxKX1+a3cvBRSosIB0xFv40kM6RYBknZ/vxabMe/ZW31Ps/WiZHlr9Wg7R7eEGli59IJ/U0iBQ1McP/ht0E2XA2TTIvYeMmKQQPsRj/eoV9j7P/wveu7skNGepU/mvpV0O2Ap7hnV5U+Prx/9+iJA/341va+pQww7jpUeHmJN9Hw4MqW0ysw0Ry3w38hOQWEpz2xwFWAxAARxeIxCxt5c37RK/lRZBlhYqoB+w2PZ74730h8pICGY4gktJxkwHyyRabpSM/G/f5DFrD9O5v8idkTZzBxW2jrbzSUIdafPtsZHL/yAMKr3HAKtaABz2nTsOBNre7X2d/jIjjarhon0Dh9l+8I9Y5Ey+DIFBcqFTvhibKAafQt3gs6CUiqHdWiCenfJyb8whmDE2qxvdxGElGmRb+k6kuN5jrZxxw95gzfYDgRHv11iEn8h1qZLD0czkIFBpMppHj9cetHPvM+qffXGAzKi8tL6eQuCdMLXmVE3jbqcJcjk9ItnaYJi5zKDz9FVbrz9qZZPtZJFHp" } ``` ### Fine-tune your ML alarms Once your ML models are built and ready for data evaluations, you can update your Security Profile's ML behavior settings to change the configuration. The following procedure shows you how to update your Security Profile's ML behavior settings in the AWS CLI. + To change your Security Profile's ML behavior settings, use the `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)` command. The following example updates the *security-profile-for-smart-lights* Security Profile's behaviors by changing the `confidenceLevel` of a few of the behaviors and unsuppresses notifications for all behaviors. ``` aws iot update-security-profile \ --security-profile-name security-profile-for-smart-lights \ --behaviors \ '[{ "name": "num-messages-sent-ml-behavior", "metric": "aws:num-messages-sent", "criteria": { "mlDetectionConfig": { "confidenceLevel" : "HIGH" } }, "suppressAlerts": false }, { "name": "num-authorization-failures-ml-behavior", "metric": "aws:num-authorization-failures", "criteria": { "mlDetectionConfig": { "confidenceLevel" : "HIGH" } }, "suppressAlerts": false }, { "name": "num-connection-attempts-ml-behavior", "metric": "aws:num-connection-attempts", "criteria": { "mlDetectionConfig": { "confidenceLevel" : "HIGH" } }, "suppressAlerts": false }, { "name": "num-disconnects-ml-behavior", "metric": "aws:num-disconnects", "criteria": { "mlDetectionConfig": { "confidenceLevel" : "LOW" } }, "suppressAlerts": false }]' ``` Output: ``` { "securityProfileName": "security-profile-for-smart-lights", "securityProfileArn": "arn:aws:iot:eu-west-1:123456789012:securityprofile/security-profile-for-smart-lights", "behaviors": [ { "name": "num-messages-sent-ml-behavior", "metric": "aws:num-messages-sent", "criteria": { "mlDetectionConfig": { "confidenceLevel": "HIGH" } } }, { "name": "num-authorization-failures-ml-behavior", "metric": "aws:num-authorization-failures", "criteria": { "mlDetectionConfig": { "confidenceLevel": "HIGH" } } }, { "name": "num-connection-attempts-ml-behavior", "metric": "aws:num-connection-attempts", "criteria": { "mlDetectionConfig": { "confidenceLevel": "HIGH" } }, "suppressAlerts": false }, { "name": "num-disconnects-ml-behavior", "metric": "aws:num-disconnects", "criteria": { "mlDetectionConfig": { "confidenceLevel": "LOW" } }, "suppressAlerts": true } ], "version": 2, "creationDate": 1600799559.249, "lastModifiedDate": 1600800516.856 } ``` ### Mark your alarm's verification state You can mark your alarms with verification states to help classify alarms and investigate anomalies. + Mark your alarms with a verification state and a description of that state. For example to set an alarm's verification state to False positive, use the following command: ``` aws iot put-verification-state-on-violation --violation-id 12345 --verification-state FALSE_POSITIVE --verification-state-description "This is dummy description" --endpoint https://us-east-1.iot.amazonaws.com --region us-east-1 ``` Output: None. ### Mitigate identified device issues 1. Use the `[create-thing-group](https://docs.aws.amazon.com/cli/latest/reference/iot/create-thing-group.html)` command to create a thing group for the mitigation action. In the following example, we create a thing group called **ThingGroupForDetectMitigationAction**. ``` aws iot create-thing-group —thing-group-name ThingGroupForDetectMitigationAction ``` Output: ``` { "thingGroupName": "ThingGroupForDetectMitigationAction", "thingGroupArn": "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroupForDetectMitigationAction", "thingGroupId": "4139cd61-10fa-4c40-b867-0fc6209dca4d" } ``` 1. Next, use the `[create-mitigation-action](https://docs.aws.amazon.com/cli/latest/reference/iot/create-mitigation-action.html)` command to create a mitigation action. In the following example, we create a mitigation action called **detect\$1mitigation\$1action** with the ARN of the IAM role that is used to apply the mitigation action. We also define the type of action and the parameters for that action. In this case, our mitigation will move things to our previously created thing group called **ThingGroupForDetectMitigationAction**. ``` aws iot create-mitigation-action --action-name detect_mitigation_action \ --role-arn arn:aws:iam::123456789012:role/MitigationActionValidRole \ --action-params \ '{ "addThingsToThingGroupParams": { "thingGroupNames": ["ThingGroupForDetectMitigationAction"], "overrideDynamicGroups": false } }' ``` Output: ``` { "actionArn": "arn:aws:iot:us-east-1:123456789012:mitigationaction/detect_mitigation_action", "actionId": "5939e3a0-bf4c-44bb-a547-1ab59ffe67c3" } ``` 1. Use the `[start-detect-mitigation-actions-task](https://docs.aws.amazon.com/cli/latest/reference/iot/start-detect-mitigation-actions-task.html)` command to start your mitigation actions task. `task-id`, `target` and `actions` are required parameters. ``` aws iot start-detect-mitigation-actions-task \ --task-id taskIdForMitigationAction \ --target '{ "violationIds" : [ "violationId-1", "violationId-2" ] }' \ --actions "detect_mitigation_action" \ --include-only-active-violations \ --include-suppressed-alerts ``` Output: ``` { "taskId": "taskIdForMitigationAction" } ``` 1. (Optional)To view mitigation action executions included in a task, use the `[list-detect-mitigation-actions-executions](https://docs.aws.amazon.com/cli/latest/reference/iot/list-detect-mitigation-actions-executions.html)` command. ``` aws iot list-detect-mitigation-actions-executions \ --task-id taskIdForMitigationAction \ --max-items 5 \ --page-size 4 ``` Output: ``` { "actionsExecutions": [ { "taskId": "e56ee95e - f4e7 - 459 c - b60a - 2701784290 af", "violationId": "214_fe0d92d21ee8112a6cf1724049d80", "actionName": "underTest_MAThingGroup71232127", "thingName": "cancelDetectMitigationActionsTaskd143821b", "executionStartDate": "Thu Jan 07 18: 35: 21 UTC 2021", "executionEndDate": "Thu Jan 07 18: 35: 21 UTC 2021", "status": "SUCCESSFUL", } ] } ``` 1. (Optional) Use the `[describe-detect-mitigation-actions-task](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-detect-mitigation-actions-task.html)` command to get information about a mitigation action task. ``` aws iot describe-detect-mitigation-actions-task \ --task-id taskIdForMitigationAction ``` Output: ``` { "taskSummary": { "taskId": "taskIdForMitigationAction", "taskStatus": "SUCCESSFUL", "taskStartTime": 1609988361.224, "taskEndTime": 1609988362.281, "target": { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "num-messages-sent-ml-behavior" }, "violationEventOccurrenceRange": { "startTime": 1609986633.0, "endTime": 1609987833.0 }, "onlyActiveViolationsIncluded": true, "suppressedAlertsIncluded": true, "actionsDefinition": [ { "name": "detect_mitigation_action", "id": "5939e3a0-bf4c-44bb-a547-1ab59ffe67c3", "roleArn": "arn:aws:iam::123456789012:role/MitigatioActionValidRole", "actionParams": { "addThingsToThingGroupParams": { "thingGroupNames": [ "ThingGroupForDetectMitigationAction" ], "overrideDynamicGroups": false } } } ], "taskStatistics": { "actionsExecuted": 0, "actionsSkipped": 0, "actionsFailed": 0 } } } ``` 1. (Optional) To get a list of your mitigation actions tasks, use the `[list-detect-mitigation-actions-tasks](https://docs.aws.amazon.com/cli/latest/reference/iot/list-detect-mitigation-actions-tasks.html)` command. ``` aws iot list-detect-mitigation-actions-tasks \ --start-time 1609985315 \ --end-time 1609988915 \ --max-items 5 \ --page-size 4 ``` Output: ``` { "tasks": [ { "taskId": "taskIdForMitigationAction", "taskStatus": "SUCCESSFUL", "taskStartTime": 1609988361.224, "taskEndTime": 1609988362.281, "target": { "securityProfileName": "security-profile-for-smart-lights", "behaviorName": "num-messages-sent-ml-behavior" }, "violationEventOccurrenceRange": { "startTime": 1609986633.0, "endTime": 1609987833.0 }, "onlyActiveViolationsIncluded": true, "suppressedAlertsIncluded": true, "actionsDefinition": [ { "name": "detect_mitigation_action", "id": "5939e3a0-bf4c-44bb-a547-1ab59ffe67c3", "roleArn": "arn:aws:iam::123456789012:role/MitigatioActionValidRole", "actionParams": { "addThingsToThingGroupParams": { "thingGroupNames": [ "ThingGroupForDetectMitigationAction" ], "overrideDynamicGroups": false } } } ], "taskStatistics": { "actionsExecuted": 0, "actionsSkipped": 0, "actionsFailed": 0 } } ] } ``` 1. (Optional) To cancel a mitigation actions task, use the `[cancel-detect-mitigation-actions-task](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-detect-mitigation-actions-task.html)` command. ``` aws iot cancel-detect-mitigation-actions-task \ --task-id taskIdForMitigationAction ``` Output: None. # Customize when and how you view AWS IoT Device Defender audit results AWS IoT Device Defender audit provides periodic security checks to confirm AWS IoT devices and resources are following best practices. For each check, the audit results are categorized as compliant or non-compliant, where non-compliance results in console warning icons. To reduce noise from repeating known issues, the audit finding suppression feature allows you to temporarily silence these non-compliance notifications. You can suppress select audit checks for a specific resource or account for a predetermined time period. An audit check result that has been suppressed is categorized as a suppressed finding, separate from the compliant and non-compliant categories. This new category doesn't trigger an alarm like a non-compliant result. This allows you to reduce non-compliance notification disturbances during known maintenance periods or until an update is scheduled to be completed. ## Getting started The following sections detail how you can use audit finding suppressions to suppress a `Device certificate expiring` check in the console and CLI. If you'd like to follow either of the demonstrations, you must first create two expiring certificates for Device Defender to detect. Use the following to create your certificates. + [Create and register a CA certificate](https://docs.aws.amazon.com/iot/latest/developerguide/create-device-cert.html) in the *AWS IoT Core Developer Guide* + [Create a client certificate using your CA certificate](https://docs.aws.amazon.com/iot/latest/developerguide/create-device-cert.html). In step 3, set your `days` parameter to **1**. If you're using the CLI to create your certificates, enter the following command. ``` openssl x509 -req \ -in device_cert_csr_filename \ -CA root_ca_pem_filename \ -CAkey root_ca_key_filename \ -CAcreateserial \ -out device_cert_pem_filename \ -days 1 -sha256 ``` ## Customize your audit findings in the console The following walkthrough uses an account with two expired device certificates that trigger a non-compliant audit check. In this scenario, we want to disable the warning because our developers are testing a new feature that'll address the problem. We create an audit finding suppression for each certificate to stop the audit result from being non-compliant for the next week. 1. We will first run an on-demand audit to show that the expired device certificate check is non-compliant. From the [AWS IoT console](https://console.aws.amazon.com/iot), choose **Defend** from the left sidebar, then **Audit**, and then **Results**. On the **Audit Results** page, choose **Create**. The **Create a new audit** window opens. Choose **Create**. ![\[Run an on-demand audit to show that the expired device certificate check is non-compliant.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-afs-noncompliant.png) From the on-demand audit results, we can see that "Device certificate expiring" is non-compliant for two resources. 1. Now, we'd like to disable the "Device certificate expiring" non-compliant check warning because our developers are testing new features that will fix the warning. From the left sidebar under **Defend**, choose **Audit**, and then choose **Finding suppressions**. On the **Audit finding suppressions** page, choose **Create**. ![\[The flow to create Audit finding suppressions in console.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-afs-suppressions.png) 1. On the **Create an audit finding suppression** window, we need to fill out the following. + **Audit check**: We select `Device certificate expiring`, because that is the audit check we'd like to suppress. + **Resource identifier**: We input the device certificate ID of one of the certificates we'd like to suppress audit findings for. + **Suppression duration**: We select `1 week`, because that's how long we'd like to suppress the `Device certificate expiring` audit check for. + **Description (optional)**: We add a note that describes why we're suppressing this audit finding. ![\[The Create an audit finding suppression page where you need to enter the detailed information.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-afs-create.png) After we've filled out the fields, choose **Create**. We see a success banner after the audit finding suppression has been created. 1. We've suppressed an audit finding for one of the certificates and now we need to suppress the audit finding for the second certificate. We could use the same suppression method that we used in step 3, but we will be using a different method for demonstration purposes. From the left sidebar under **Defend**, choose **Audit**, and then choose **Results**. On the **Audit results** page, choose the audit with the non-compliant resource. Then, select the resource under **Non-compliant checks**. In our case, we select "Device certificate expiring". 1. On the **Device certificate expiring** page, under **Non-compliant policy** choose the option button next to the finding that needs to be suppressed. Next, choose the **Actions** dropdown menu, and then choose the duration for which you'd like finding to be suppressed. In our case, we choose `1 week` as we did for the other certificate. On the **Confirm suppression** window, choose **Enable suppression**. ![\[The Create an audit suppression page where you complete the flow. You will see a success banner after the audit finding suppression has been created.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/dd-afs-noncompliantcerts.png) We see a success banner after the audit finding suppression has been created. Now, both audit findings have been suppressed for 1 week while our developers work on a solution to address the warning. ## Customize your audit findings in the CLI The following walkthrough uses an account with an expired device certificate that trigger a non-compliant audit check. In this scenario, we want to disable the warning because our developers are testing a new feature that'll address the problem. We create an audit finding suppression for the certificate to stop the audit result from being non-compliant for the next week. We use the following CLI commands. + [create-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/create-audit-suppression.html) + [describe-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-audit-suppression.html) + [update-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/update-audit-suppression.html) + [delete-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-audit-suppression.html) + [list-audit-suppressions](https://docs.aws.amazon.com/cli/latest/reference/iot/list-audit-suppressions.html) 1. Use the following command to enable the audit. ``` aws iot update-account-audit-configuration \ --audit-check-configurations "{\"DEVICE_CERTIFICATE_EXPIRING_CHECK\":{\"enabled\":true}}" ``` Output: None. 1. Use the following command to run an on-demand audit that targets the `DEVICE_CERTIFICATE_EXPIRING_CHECK` audit check. ``` aws iot start-on-demand-audit-task \ --target-check-names DEVICE_CERTIFICATE_EXPIRING_CHECK ``` Output: ``` { "taskId": "787ed873b69cb4d6cdbae6ddd06996c5" } ``` 1. Use the [describe-account-audit-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-account-audit-configuration.html) command to describe the audit configuration. We want to confirm that we've turned on the audit check for `DEVICE_CERTIFICATE_EXPIRING_CHECK`. ``` aws iot describe-account-audit-configuration ``` Output: ``` { "roleArn": "arn:aws:iam:::role/service-role/project", "auditNotificationTargetConfigurations": { "SNS": { "targetArn": "arn:aws:sns:us-east-1::project_sns", "roleArn": "arn:aws:iam:::role/service-role/project", "enabled": true } }, "auditCheckConfigurations": { "AUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK": { "enabled": false }, "CA_CERTIFICATE_EXPIRING_CHECK": { "enabled": false }, "CA_CERTIFICATE_KEY_QUALITY_CHECK": { "enabled": false }, "CONFLICTING_CLIENT_IDS_CHECK": { "enabled": false }, "DEVICE_CERTIFICATE_EXPIRING_CHECK": { "enabled": true }, "DEVICE_CERTIFICATE_KEY_QUALITY_CHECK": { "enabled": false }, "DEVICE_CERTIFICATE_SHARED_CHECK": { "enabled": false }, "IOT_POLICY_OVERLY_PERMISSIVE_CHECK": { "enabled": true }, "IOT_ROLE_ALIAS_ALLOWS_ACCESS_TO_UNUSED_SERVICES_CHECK": { "enabled": false }, "IOT_ROLE_ALIAS_OVERLY_PERMISSIVE_CHECK": { "enabled": false }, "LOGGING_DISABLED_CHECK": { "enabled": false }, "REVOKED_CA_CERTIFICATE_STILL_ACTIVE_CHECK": { "enabled": false }, "REVOKED_DEVICE_CERTIFICATE_STILL_ACTIVE_CHECK": { "enabled": false }, "UNAUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK": { "enabled": false } } } ``` `DEVICE_CERTIFICATE_EXPIRING_CHECK` should have a value of `true`. 1. Use the [list-audit-task](https://docs.aws.amazon.com/cli/latest/reference/iot/list-audit-task.html) command to identify the completed audit tasks. ``` aws iot list-audit-tasks \ --task-status "COMPLETED" \ --start-time 2020-07-31 \ --end-time 2020-08-01 ``` Output: ``` { "tasks": [ { "taskId": "787ed873b69cb4d6cdbae6ddd06996c5", "taskStatus": "COMPLETED", "taskType": "SCHEDULED_AUDIT_TASK" } ] } ``` The `taskId` of the audit you ran in step 1 should have a `taskStatus` of `COMPLETED`. 1. Use the [describe-audit-task](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-audit-task.html) command to get details about the completed audit using the `taskId` output from the previous step. This command lists details about your audit. ``` aws iot describe-audit-task \ --task-id "787ed873b69cb4d6cdbae6ddd06996c5" ``` Output: ``` { "taskStatus": "COMPLETED", "taskType": "SCHEDULED_AUDIT_TASK", "taskStartTime": 1596168096.157, "taskStatistics": { "totalChecks": 1, "inProgressChecks": 0, "waitingForDataCollectionChecks": 0, "compliantChecks": 0, "nonCompliantChecks": 1, "failedChecks": 0, "canceledChecks": 0 }, "scheduledAuditName": "AWSIoTDeviceDefenderDailyAudit", "auditDetails": { "DEVICE_CERTIFICATE_EXPIRING_CHECK": { "checkRunStatus": "COMPLETED_NON_COMPLIANT", "checkCompliant": false, "totalResourcesCount": 195, "nonCompliantResourcesCount": 2 } } } ``` 1. Use the [list-audit-findings](https://docs.aws.amazon.com/cli/latest/reference/iot/list-audit-findings.html) command to find the non-compliant certificate ID so that we can suspend the audit alerts for this resource. ``` aws iot list-audit-findings \ --start-time 2020-07-31 \ --end-time 2020-08-01 ``` Output: ``` { "findings": [ { "findingId": "296ccd39f806bf9d8f8de20d0ceb33a1", "taskId": "787ed873b69cb4d6cdbae6ddd06996c5", "checkName": "DEVICE_CERTIFICATE_EXPIRING_CHECK", "taskStartTime": 1596168096.157, "findingTime": 1596168096.651, "severity": "MEDIUM", "nonCompliantResource": { "resourceType": "DEVICE_CERTIFICATE", "resourceIdentifier": { "deviceCertificateId": "b4490" }, "additionalInfo": { "EXPIRATION_TIME": "1582862626000" } }, "reasonForNonCompliance": "Certificate is past its expiration.", "reasonForNonComplianceCode": "CERTIFICATE_PAST_EXPIRATION", "isSuppressed": false }, { "findingId": "37ecb79b7afb53deb328ec78e647631c", "taskId": "787ed873b69cb4d6cdbae6ddd06996c5", "checkName": "DEVICE_CERTIFICATE_EXPIRING_CHECK", "taskStartTime": 1596168096.157, "findingTime": 1596168096.651, "severity": "MEDIUM", "nonCompliantResource": { "resourceType": "DEVICE_CERTIFICATE", "resourceIdentifier": { "deviceCertificateId": "c7691" }, "additionalInfo": { "EXPIRATION_TIME": "1583424717000" } }, "reasonForNonCompliance": "Certificate is past its expiration.", "reasonForNonComplianceCode": "CERTIFICATE_PAST_EXPIRATION", "isSuppressed": false } ] } ``` 1. Use the [create-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/create-audit-suppression.html) command to suppress notifications for the `DEVICE_CERTIFICATE_EXPIRING_CHECK` audit check for a device certificate with the id `c7691e` until *2020-08-20*. ``` aws iot create-audit-suppression \ --check-name DEVICE_CERTIFICATE_EXPIRING_CHECK \ --resource-identifier deviceCertificateId="c7691e" \ --no-suppress-indefinitely \ --expiration-date 2020-08-20 ``` 1. Use the [list-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/list-audit-suppression.html) command to confirm the audit suppression setting and get details about the suppression. ``` aws iot list-audit-suppressions ``` Output: ``` { "suppressions": [ { "checkName": "DEVICE_CERTIFICATE_EXPIRING_CHECK", "resourceIdentifier": { "deviceCertificateId": "c7691e" }, "expirationDate": 1597881600.0, "suppressIndefinitely": false } ] } ``` 1. The [update-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/update-audit-suppression.html) command can be used to update the audit finding suppression. The example below updates the `expiration-date` to `08/21/20`. ``` aws iot update-audit-suppression \ --check-name DEVICE_CERTIFICATE_EXPIRING_CHECK \ --resource-identifier deviceCertificateId=c7691e \ --no-suppress-indefinitely \ --expiration-date 2020-08-21 ``` 1. The [delete-audit-suppression](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-audit-suppression.html) command can be used to remove an audit finding suppression. ``` aws iot delete-audit-suppression \ --check-name DEVICE_CERTIFICATE_EXPIRING_CHECK \ --resource-identifier deviceCertificateId="c7691e" ``` To confirm deletion, use the [list-audit-suppressions](https://docs.aws.amazon.com/cli/latest/reference/iot/list-audit-suppressions.html) command. ``` aws iot list-audit-suppressions ``` Output: ``` { "suppressions": [] } ``` In this tutorial, we showed you how to suppress a `Device certificate expiring` check in the console and CLI. For more information about audit finding suppressions, see [Audit finding suppressions](audit-finding-suppressions.md)