AWS IoT
Developer Guide

Mitigation Actions

You can use AWS IoT Device Defender to take actions to mitigate issues that were found during an audit. AWS IoT Device Defender provides predefined actions for the different audit checks. You configure those actions for your AWS account and then apply them to a set of findings. Those findings can be:

  • All findings from an audit. This option is available in both the AWS IoT console and by using the AWS CLI.

  • A list of individual findings. This option is only available by using the AWS CLI.

  • A filtered set of findings from an audit. This option is not available in the beta release.

The following table lists the types of audit checks and the supported mitigation actions for each:

Audit Check to Mitigation Action Mapping

Audit Check Supported Mitigation Actions
REVOKED_CA_CERT_CHECK PUBLISH_FINDING_TO_SNS, UPDATE_CA_CERTIFICATE
DEVICE_CERTIFICATE_SHARED_CHECK PUBLISH_FINDING_TO_SNS, UPDATE_DEVICE_CERTIFICATE, ADD_THINGS_TO_THING_GROUP
UNAUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK PUBLISH_FINDING_TO_SNS
AUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK PUBLISH_FINDING_TO_SNS
IOT_POLICY_OVERLY_PERMISSIVE_CHECK PUBLISH_FINDING_TO_SNS, REPLACE_DEFAULT_POLICY_VERSION
CA_CERT_APPROACHING_EXPIRATION_CHECK PUBLISH_FINDING_TO_SNS, UPDATE_CA_CERTIFICATE
CONFLICTING_CLIENT_IDS_CHECK PUBLISH_FINDING_TO_SNS
DEVICE_CERT_APPROACHING_EXPIRATION_CHECK PUBLISH_FINDING_TO_SNS, UPDATE_DEVICE_CERTIFICATE, ADD_THINGS_TO_THING_GROUP
REVOKED_DEVICE_CERT_CHECK PUBLISH_FINDING_TO_SNS, UPDATE_DEVICE_CERTIFICATE, ADD_THINGS_TO_THING_GROUP
LOGGING_DISABLED_CHECK PUBLISH_FINDING_TO_SNS, ENABLE_IOT_LOGGING

All audit checks support publishing the audit findings to Amazon SNS so you can take custom actions in response to the notification. Each type of audit check can support additional mitigation actions:

REVOKED_CA_CERT_CHECK
  • Change the state of the certificate to mark it as inactive in AWS IoT.

DEVICE_CERTIFICATE_SHARED_CHECK
  • Change the state of the device certificate to mark it as inactive in AWS IoT.

  • Add the devices that use that certificate to a thing group.

UNAUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK
  • No additional supported actions.

AUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK
  • No additional supported actions.

IOT_POLICY_OVERLY_PERMISSIVE_CHECK
  • Add a blank AWS IoT policy version to restrict permissions.

CA_CERT_APPROACHING_EXPIRATION_CHECK
  • Change the state of the certificate to mark it as inactive in AWS IoT.

CONFLICTING_CLIENT_IDS_CHECK
  • No additional supported actions.

DEVICE_CERT_APPROACHING_EXPIRATION_CHECK
  • Change the state of the device certificate to mark it as inactive in AWS IoT.

  • Add the devices that use that certificate to a thing group.

REVOKED_DEVICE_CERT_CHECK
  • Change the state of the device certificate to mark it as inactive in AWS IoT.

  • Add the devices that use that certificate to a thing group.

LOGGING_DISABLED_CHECK
  • Enable logging.

AWS IoT Device Defender supports the following types of mitigation actions:

Action type

Notes
ADD_THINGS_TO_THING_GROUP You specify the group to which you want to add the devices. You also specify whether membership in one or more dynamic groups should be overridden if that would exceed the maximum number of groups to which the thing can belong.
ENABLE_IOT_LOGGING You specify the logging level and the role with permissions for logging. You cannot specify a logging level of DISABLED.
PUBLISH_FINDING_TO_SNS You specify the topic to which the finding should be published.
REPLACE_DEFAULT_POLICY_VERSION You specify the template name. Replaces the policy version with a default or blank policy. Only a value of BLANK_POLICY is currently supported.
UPDATE_CA_CERTIFICATE You specify the new state for the CA certificate. Only a value of DEACTIVATE is currently supported.
UPDATE_DEVICE_CERTIFICATE You specify the new state for the device certificate. Only a value of DEACTIVATE is currently supported.

By configuring standard actions when issues are found during an audit, you can respond to those issues consistently. Using these defined mitigation actions also helps you resolve the issues more quickly and with less chance of human error.

Important

Applying mitigation actions that change certificates, add things to a new thing group, or replace the policy can have an impact on your devices and applications. For example, devices might be unable to connect. Consider the implications of the mitigation actions before you apply them. You might need to take other actions to correct the problems before your devices and applications can function normally. For example, you might need to provide updated device certificates. Mitigation actions can help you quickly limit your risk, but you must still take corrective actions to address the underlying issues.

Some actions, such as reactivating a device certificate, can only be performed manually. AWS IoT Device Defender does not provide a mechanism to automatically roll back mitigation actions that have been applied.

How to Define and Manage Mitigation Actions

Each mitigation action that you define is a combination of a predefined action type and parameters specific to your account.

Create Mitigation Actions

To use the AWS IoT console to create mitigation actions

You can use the AWS IoT console or the AWS CLI to define and manage mitigation actions for your AWS account.

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, and then choose Mitigation Actions.

  3. On the Mitigation Actions page, choose Create.

    
                            Create a new mitigation action window.
  4. On the Create a Mitigation Action page, in Action name, enter a unique name for your mitigation action.

  5. In Action type, specify the type of action that you want to define.

  6. Each action type requests a different set of parameters. Enter the parameters for the action. For example, if you choose the Add things to thing group action type, choose the destination group and select or clear Override dynamic groups.

  7. In Action execution role, choose the role under whose permissions the action is applied.

  8. Choose Save to save your mitigation action to your AWS account.

To use the AWS CLI to create mitigation actions

  • Use the CreateMitigationAction command to create your mitigation action. The unique name that you give the action is used when you apply that action to audit findings. Choose a meaningful name.

To use the AWS IoT console to view and modify mitigation actions

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, and then choose Mitigation Actions.

    The Mitigation Actions page displays a list of all of the mitigation actions that are defined for your AWS account.

    
                            List of mitigation actions.
  3. Choose the action name link for the mitigation action that you want to change.

  4. Make your changes to the mitigation action. Because the name of the mitigation action is used to identify it, you cannot change the name.

    
                            Edit mitigation action window.
  5. Choose Save to save the changes to the mitigation action to your AWS account.

To use the AWS CLI to list mitigation action

  • Use the ListMitigationActions command to list your mitigation actions. If you want to change or delete a mitigation action, make a note of the name.

To use the AWS CLI to update mitigation action

To use the AWS IoT console to delete mitigation actions

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, and then choose Mitigation Actions.

    The Mitigation Actions page displays all of the mitigation actions that are defined for your AWS account.

  3. Choose the ellipsis (...) for the mitigation action that you want to delete, and then choose Delete.

To use the AWS CLI to delete mitigation actions

To use the AWS IoT console to view mitigation action details

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, and then choose Mitigation Actions.

    
                            List of mitigation actions.

    The Mitigation Actions page displays all of the mitigation actions that are defined for your AWS account.

  3. Choose the action name link for the mitigation action that you want to change.

  4. In the Are you sure you want to delete the mitigation action window, choose Confirm.

    
                            Are you sure you want to delete the mitigation action confirmation window.

To use the AWS CLI to view mitigation action details

Apply Mitigation Actions

After you have defined a set of mitigation actions, you can apply those actions to the findings from an audit. When you apply actions, you start an audit mitigation actions task. This task might take some time to complete, depending on the set of findings and the actions that you apply to them. For example, if you have a large pool of devices whose certificates have expired, it might take some time to deactivate all of those certificates or to move those devices to a quarantine group. Other actions, such as enabling logging, can be completed quickly.

You can view the list of action executions and cancel an execution that has not yet been completed. Actions already performed as part of the canceled action execution are not rolled back. If you are applying multiple actions to a set of findings and one of those actions failed, the subsequent actions are skipped for that finding (but are still applied to other findings). The task status for the finding is FAILED. The taskStatus is set to failed if one or more of the actions failed when applied to the findings. Actions are applied in the order in which they are specified.

Each action execution applies a set of actions to a target. That target can be a list of findings or it can be all findings from an audit.

The following diagram shows how you can define an audit mitigation task that takes all findings from one audit and applies a set of actions to those findings. A single execution applies one action to one finding. The audit mitigation actions task outputs an execution summary.


                Conceptual image shows an audit mitigation actions task.

The following diagram shows how you can define an audit mitigation task that takes a list of individual findings from one or more audits and applies a set of actions to those findings. A single execution applies one action to one finding. The audit mitigation actions task outputs an execution summary.


                Conceptual image shows an audit mitigation actions task.

You can use the AWS IoT console or the AWS CLI to apply mitigation actions.

To use the AWS IoT console to apply mitigation actions by starting an action execution

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, choose Audit, and then choose Results.

    
                        List of audit results that shows the Start mitigation actions button.
  3. Choose the name for the audit to which you want to apply actions.

    
                        Are you sure you want to start mitigation action task window.
  4. Choose Start Mitigation Actions. This button is not available if all of your checks are compliant.

  5. In Are you sure that you want to start mitigation action task, the task name defaults to the audit ID, but you can change it to something more meaningful.

  6. For each type of check that had one or more noncompliant findings in the audit, you can choose one or more actions to apply. Only actions that are valid for the check type are displayed.

    Note

    If you have not configured actions for your AWS account, the list of applicable actions is empty. You can choose the click here link to create one or more mitigation actions.

  7. When you have specified all of the actions that you want to apply, choose Confirm.

To use the AWS CLI to apply mitigation actions by starting an audit mitigation actions execution

  1. If you want to apply actions to all findings for the audit, use the ListAuditTasks command to find the task ID.

  2. If you want to apply actions to selected findings only, use the ListAuditFindings command to get the finding IDs.

  3. Use the ListMitigationActions command and make note of the names of the mitigation actions that you want to apply.

  4. Use the StartAuditMitigationActionsTask command to apply actions to the target. Make note of the task ID. You can use the ID to check the state of the action execution, review the details, or cancel it.

To use the AWS IoT console to view your action executions

  1. Open the AWS IoT console.

  2. In the left navigation pane, choose Defend, and then choose Action Executions.

    
                        List of audit action executions.

    A list of action tasks shows when each was started and the current status.

  3. Choose the Name link to see details for the task. The details include all of the actions that are applied by the task, their target, and their status.

    
                        Details for the audit mitigation action task.

    You can use the Show executions for filters to focus on specific types of actions or actions in a particular state.

  4. To see details for the task, in Executions, choose Show for the task whose execution details you want to view.

    
                        Execution details for the audit mitigation action task.

To use the AWS CLI to list your started tasks

  1. Use ListAuditMitigationActionsTasks to view your audit mitigation actions tasks. You can provide filters to narrow the results. Make note of the task ID for any tasks for which you want to view more details.

  2. Use ListAuditMitigationActionsExecutions to view execution details for a particular audit mitigation actions task.

  3. Use DescribeAuditMitigationActionsTask to view details about the task, such as the parameters specified when it was started.

To use the AWS CLI to cancel a running audit mitigation actions task

  1. Use the ListAuditMitigationActionsTasks command to find the task ID for the task whose execution you want to cancel. You can provide filters to narrow the results.

  2. Use the CancelAuditMitigationActionsTask command, using the task ID, to cancel your audit mitigation actions task. You cannot cancel tasks that have been completed. When you cancel a task, remaining actions are not applied, but mitigation actions that were already applied are not rolled back.

Permissions

For each mitigation action that you define, you must provide the role used to apply that action.

Permissions for Mitigation Actions

Action Type Permissions Policy Template

UPDATE_DEVICE_CERTIFICATE

{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:UpdateCertificate" ], "Resource":[ "*" ] } ] }
UPDATE_CA_CERTIFICATE
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:UpdateCACertificate" ], "Resource":[ "*" ] } ] }
ADD_THINGS_TO_THING_GROUP
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:ListPrincipalThings", "iot:AddThingToThingGroup" ], "Resource":[ "*" ] } ] }
REPLACE_DEFAULT_POLICY_VERSION
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:CreatePolicyVersion" ], "Resource":[ "*" ] } ] }
ENABLE_IOT_LOGGING
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:SetV2LoggingOptions" ], "Resource":[ "*" ] }, { "Effect":"Allow", "Action":[ "iam:PassRole" ], "Resource":[ "<IAM role ARN used for setting up logging>" ] } ] }
PUBLISH_FINDING_TO_SNS
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "sns:Publish" ], "Resource":[ "<The SNS topic to which the finding will be published>" ] } ] }

For all mitigation action types, use the following trust policy template:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

Service Limits

The following service limits apply to mitigation actions and audit mitigation action tasks:

Resource Limit
Maximum number of mitigation actions in an AWS account 100 actions
Maximum number of audit mitigation action tasks running at the same time 10 tasks
Retention period for audit mitigation action tasks 90 days