# Audit
An AWS IoT Device Defender audit looks at account- and device-related settings and policies to ensure security measures are in place. An audit can help you detect any drifts from security best practices or access policies (for example, multiple devices using the same identity, or overly permissive policies that allow one device to read and update data for many other devices). You can run audits as needed (*on-demand audits*) or schedule them to be run periodically (*scheduled audits*).
An AWS IoT Device Defender audit runs a set of predefined checks for common IoT security best practices and device vulnerabilities. Examples of predefined checks include policies that grant permission to read or update data on multiple devices, devices that share an identity (X.509 certificate), or certificates that are expiring or have been revoked but are still active.
## Issue severity
Issue severity indicates the level of concern associated with each identified instance of noncompliance and the recommended time to remediation.
**Critical**
Non compliant audit checks with this severity identify issues that require urgent attention. Critical issues often allow bad actors with little sophistication and no insider knowledge or special credentials to easily gain access to or control of your assets.
**High**
Non compliant audit checks with this severity require urgent investigation and remediation planning after critical issues are addressed. Like critical issues, high severity issues often provide bad actors with access to or control of your assets. However, high severity issues are often more difficult to exploit. They might require special tools, insider knowledge, or specific setups.
**Medium**
Non compliant audit checks with this severity present issues that need attention as part of your continuous security posture maintenance. Medium severity issues might cause negative operational impact, such as unplanned outages due to malfunction of security controls. These issues might also provide bad actors with limited access to or control of your assets, or might facilitate parts of their malicious actions.
**Low**
Non compliant audit checks with this severity often indicate security best practices were overlooked or bypassed. Although they might not cause an immediate security impact on their own, these lapses can be exploited by bad actors. Like medium severity issues, low severity issues require attention as part of your continuous security posture maintenance.
## Next steps
To understand the types of audit checks that can be performed, see [Audit checks](device-defender-audit-checks.md). For information about service quotas that apply to audits, see [Service Quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot).
# Audit checks
**Note**
When you enable a check, data collection starts immediately. If there is a large amount of data in your account to collect, results of the check might not be available for some time after you enabled it.
The following audit checks are supported:
+ [Intermediate CA revoked for active device certificates check](audit-chk-active-intermediary-device-revoked-CA.md)
+ [Revoked CA certificate still active](audit-chk-revoked-ca-cert.md)
+ [Device certificate shared](audit-chk-device-cert-shared.md)
+ [Device certificate key quality](audit-chk-device-cert-key-quality.md)
+ [CA certificate key quality](audit-chk-ca-cert-key-quality.md)
+ [Unauthenticated Cognito role overly permissive](audit-chk-unauth-cognito-role-permissive.md)
+ [Authenticated Cognito role overly permissive](audit-chk-auth-cognito-role-permissive.md)
+ [AWS IoT policies overly permissive](audit-chk-iot-policy-permissive.md)
+ [AWS IoT policy potentially misconfigured](audit-chk-iot-misconfigured-policies.md)
+ [Role alias overly permissive](audit-chk-iot-role-alias-permissive.md)
+ [Role alias allows access to unused services](audit-chk-role-alias-unused-svcs.md)
+ [CA certificate expiring](audit-chk-ca-cert-approaching-expiration.md)
+ [Conflicting MQTT client IDs](audit-chk-conflicting-client-ids.md)
+ [Device certificate expiring](audit-chk-device-cert-approaching-expiration.md)
+ [Device certificate age check](device-certificate-age-check.md)
+ [Revoked device certificate still active](audit-chk-revoked-device-cert.md)
+ [Logging disabled](audit-chk-logging-disabled.md)
# Intermediate CA revoked for active device certificates check
Use this check to identify all related device certificates that are still active despite revoking an intermediate CA.
This check appears as `INTERMEDIATE_CA_REVOKED_FOR_ACTIVE_DEVICE_CERTIFICATES_CHECK` in the CLI and API.
Severity: **Critical**
## Details
The following reason codes are returned when this check finds noncompliance:
+ INTERMEDIATE\$1CA\$1REVOKED\$1BY\$1ISSUER
## Why it matters
The intermediate CA revoked for active device certificates check assess device identity and trust, by determining if there are active device certificates in AWS IoT Core where the intermediate issuing CAs have been revoked in the CA chain.
A revoked intermediate CA should no longer be used to sign any other CA or device certificates in CA chain. Newly added devices with certificates signed using this CA certificate after the intermediate CA is revoked will pose a security threat.
## How to fix it
Review the device certificate registration activity for the time after the CA certificate was revoked. Follow your security best practices to mitigate the situation. You might want to:
1. Provision new certificates, that are signed by a different CA, for the affected devices.
1. Verify that the new certificates are valid, and that the devices can use them to connect.
1. Use [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to mark the old certificate as REVOKED in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_DEVICE_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `ADD_THINGS_TO_THING_GROUP` mitigation action to add the device to a group where you can take action on it.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
+ Review the device certificate registration activity for the time after the intermediate CA certificate was revoked and consider revoking any device certificates that might have been issued with it during this time. You can use [ListRelatedResourcesForAuditFinding](https://docs.aws.amazon.com/iot/latest/apireference/API_ListRelatedResourcesForAuditFinding.html) to list the device certificates signed by the CA certificate and [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to revoke a device certificate.
+ Detach the old certificate from the device. (See [DetachThingPrincipal](https://docs.aws.amazon.com/iot/latest/apireference/API_DetachThingPrincipal.html).)
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# Revoked CA certificate still active
A CA certificate was revoked, but is still active in AWS IoT.
This check appears as `REVOKED_CA_CERTIFICATE_STILL_ACTIVE_CHECK` in the CLI and API.
Severity: **Critical**
## Details
A CA certificate is marked as revoked in the certificate revocation list maintained by the issuing authority, but is still marked as ACTIVE or PENDING\$1TRANSFER in AWS IoT.
The following reason codes are returned when this check finds a noncompliant CA certificate:
+ CERTIFICATE\$1REVOKED\$1BY\$1ISSUER
## Why it matters
A revoked CA certificate should no longer be used to sign device certificates. It might have been revoked because it was compromised. Newly added devices with certificates signed using this CA certificate might pose a security threat.
## How to fix it
1. Use [UpdateCACertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCACertificate.html) to mark the CA certificate as INACTIVE in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_CA_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Review the device certificate registration activity for the time after the CA certificate was revoked and consider revoking any device certificates that might have been issued with it during this time. You can use [ListCertificatesByCA](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCertificatesByCA.html) to list the device certificates signed by the CA certificate and [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to revoke a device certificate.
# Device certificate shared
Multiple, concurrent connections use the same X.509 certificate to authenticate with AWS IoT.
This check appears as `DEVICE_CERTIFICATE_SHARED_CHECK` in the CLI and API.
Severity: **Critical**
## Details
When performed as part of an on-demand audit, this check looks at the certificates and client IDs that were used by devices to connect during the 31 days before the start of the audit up to 2 hours before the check is run. For scheduled audits, this check looks at data from 2 hours before the last time the audit was run to 2 hours before the time this instance of the audit started. If you have taken steps to mitigate this condition during the time checked, note when the concurrent connections were made to determine if the problem persists.
The following reason codes are returned when this check finds a noncompliant certificate:
+ CERTIFICATE\$1SHARED\$1BY\$1MULTIPLE\$1DEVICES
In addition, the findings returned by this check include the ID of the shared certificate, the IDs of the clients using the certificate to connect, and the connect/disconnect times. Most recent results are listed first.
## Why it matters
Each device should have a unique certificate to authenticate with AWS IoT. When multiple devices use the same certificate, this might indicate that a device has been compromised. Its identity might have been cloned to further compromise the system.
## How to fix it
Verify that the device certificate has not been compromised. If it has, follow your security best practices to mitigate the situation.
If you use the same certificate on multiple devices, you might want to:
1. Provision new, unique certificates and attach them to each device.
1. Verify that the new certificates are valid and the devices can use them to connect.
1. Use [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to mark the old certificate as REVOKED in AWS IoT. You can also use mitigation actions to do the following:
+ Apply the `UPDATE_DEVICE_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `ADD_THINGS_TO_THING_GROUP` mitigation action to add the device to a group where you can take action on it.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Detach the old certificate from each of the devices.
# Device certificate key quality
AWS IoT customers often rely on TLS mutual authentication using X.509 certificates for authenticating to AWS IoT message broker. These certificates and their certificate authority certificates must be registered in their AWS IoT account before they are used. AWS IoT performs basic sanity checks on these certificates when they are registered. These checks include:
+ They must be in a valid format.
+ They must be signed by a registered certificate authority.
+ They must still be within their validity period (in other words, they haven't expired).
+ Their cryptographic key sizes must meet a minimum required size (for RSA keys, they must be 2048 bits or larger).
This audit check provides the following additional tests of the quality of your cryptographic key:
+ CVE-2008-0166 – Check whether the key was generated using OpenSSL 0.9.8c-1 up to versions before 0.9.8g-9 on a Debian-based operating system. Those versions of OpenSSL use a random number generator that generates predictable numbers, making it easier for remote attackers to conduct brute force guessing attacks against cryptographic keys.
+ CVE-2017-15361 – Check whether the key was generated by the Infineon RSA library 1.02.013 in Infineon Trusted Platform Module (TPM) firmware, such as versions before 0000000000000422 – 4.34, before 000000000000062b – 6.43, and before 0000000000008521 – 133.33. That library mishandles RSA key generation, making it easier for attackers to defeat some cryptographic protection mechanisms through targeted attacks. Examples of affected technologies include BitLocker with TPM 1.2, YubiKey 4 (before 4.3.5) PGP key generation, and the Cached User Data encryption feature in Chrome OS.
AWS IoT Device Defender reports certificates as noncompliant if they fail these tests.
This check appears as `DEVICE_CERTIFICATE_KEY_QUALITY_CHECK` in the CLI and API.
Severity: **Critical**
## Details
This check applies to device certificates that are ACTIVE or PENDING\$1TRANSFER.
The following reason codes are returned when this check finds a noncompliant certificate:
+ CERTIFICATE\$1KEY\$1VULNERABILITY\$1CVE-2017-15361
+ CERTIFICATE\$1KEY\$1VULNERABILITY\$1CVE-2008-0166
## Why it matters
When a device uses a vulnerable certificate, attackers can more easily compromise that device.
## How to fix it
Update your device certificates to replace those with known vulnerabilities.
If you are using the same certificate on multiple devices, you might want to:
1. Provision new, unique certificates and attach them to each device.
1. Verify that the new certificates are valid and the devices can use them to connect.
1. Use [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to mark the old certificate as REVOKED in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_DEVICE_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `ADD_THINGS_TO_THING_GROUP` mitigation action to add the device to a group where you can take action on it.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Detach the old certificate from each of the devices.
# CA certificate key quality
AWS IoT customers often rely on TLS mutual authentication using X.509 certificates for authenticating to AWS IoT message broker. These certificates and their certificate authority certificates must be registered in their AWS IoT account before they are used. AWS IoT performs basic sanity checks on these certificates when they are registered, including:
+ The certificates are in a valid format.
+ The certificates are within their validity period (in other words, not expired).
+ Their cryptographic key sizes meet a minimum required size (for RSA keys, they must be 2048 bits or larger).
This audit check provides the following additional tests of the quality of your cryptographic key:
+ CVE-2008-0166 – Check whether the key was generated using OpenSSL 0.9.8c-1 up to versions before 0.9.8g-9 on a Debian-based operating system. Those versions of OpenSSL use a random number generator that generates predictable numbers, making it easier for remote attackers to conduct brute force guessing attacks against cryptographic keys.
+ CVE-2017-15361 – Check whether the key was generated by the Infineon RSA library 1.02.013 in Infineon Trusted Platform Module (TPM) firmware, such as versions before 0000000000000422 – 4.34, before 000000000000062b – 6.43, and before 0000000000008521 – 133.33. That library mishandles RSA key generation, making it easier for attackers to defeat some cryptographic protection mechanisms through targeted attacks. Examples of affected technologies include BitLocker with TPM 1.2, YubiKey 4 (before 4.3.5) PGP key generation, and the Cached User Data encryption feature in Chrome OS.
AWS IoT Device Defender reports certificates as noncompliant if they fail these tests.
This check appears as `CA_CERTIFICATE_KEY_QUALITY_CHECK` in the CLI and API.
Severity: **Critical**
## Details
This check applies to CA certificates that are ACTIVE or PENDING\$1TRANSFER.
The following reason codes are returned when this check finds a noncompliant certificate:
+ CERTIFICATE\$1KEY\$1VULNERABILITY\$1CVE-2017-15361
+ CERTIFICATE\$1KEY\$1VULNERABILITY\$1CVE-2008-0166
## Why it matters
Newly added devices signed using this CA certificate might pose a security threat.
## How to fix it
1. Use [UpdateCACertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCACertificate.html) to mark the CA certificate as INACTIVE in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_CA_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Review the device certificate registration activity for the time after the CA certificate was revoked and consider revoking any device certificates that might have been issued with it during this time. (Use [ListCertificatesByCA](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCertificatesByCA.html) to list the device certificates signed by the CA certificate and [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to revoke a device certificate.)
# Unauthenticated Cognito role overly permissive
A policy attached to an unauthenticated Amazon Cognito identity pool role is considered too permissive because it grants permission to perform any of the following AWS IoT actions:
+ Manage or modify things.
+ Read thing administrative data.
+ Manage non-thing related data or resources.
Or, because it grants permission to perform the following AWS IoT actions on a broad set of devices:
+ Use MQTT to connect, publish, or subscribe to reserved topics (including shadow or job execution data).
+ Use API commands to read or modify shadow or job execution data.
In general, devices that connect using an unauthenticated Amazon Cognito identity pool role should have only limited permission to publish and subscribe to thing-specific MQTT topics or use the API commands to read and modify thing-specific data related to shadow or job execution data.
This check appears as `UNAUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK` in the CLI and API.
Severity: **Critical**
## Details
For this check, AWS IoT Device Defender audits all Amazon Cognito identity pools that have been used to connect to the AWS IoT message broker during the 31 days before the audit execution. All Amazon Cognito identity pools from which either an authenticated or unauthenticated Amazon Cognito identity connected are included in the audit.
The following reason codes are returned when this check finds a noncompliant unauthenticated Amazon Cognito identity pool role:
+ ALLOWS\$1ACCESS\$1TO\$1IOT\$1ADMIN\$1ACTIONS
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1IOT\$1DATA\$1PLANE\$1ACTIONS
## Why it matters
Because unauthenticated identities are never authenticated by the user, they pose a much greater risk than authenticated Amazon Cognito identities. If an unauthenticated identity is compromised, it can use administrative actions to modify account settings, delete resources, or gain access to sensitive data. Or, with broad access to device settings, it can access or modify shadows and jobs for all devices in your account. A guest user might use the permissions to compromise your entire fleet or launch a DDOS attack with messages.
## How to fix it
A policy attached to an unauthenticated Amazon Cognito identity pool role should grant only those permissions required for a device to do its job. We recommend the following steps:
1. Create a new compliant role.
1. Create a Amazon Cognito identity pool and attach the compliant role to it.
1. Verify that your identities can access AWS IoT using the new pool.
1. After verification is complete, attach the compliant role to the Amazon Cognito identity pool that was flagged as noncompliant.
You can also use mitigation actions to:
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
## Manage or modify things
The following AWS IoT API actions are used to manage or modify things. Permission to perform these actions should not be granted to devices that connect through an unauthenticated Amazon Cognito identity pool.
+ `AddThingToThingGroup`
+ `AttachThingPrincipal`
+ `CreateThing`
+ `DeleteThing`
+ `DetachThingPrincipal`
+ `ListThings`
+ `ListThingsInThingGroup`
+ `RegisterThing`
+ `RemoveThingFromThingGroup`
+ `UpdateThing`
+ `UpdateThingGroupsForThing`
Any role that grants permission to perform these actions on even a single resource is considered noncompliant.
## Read thing administrative data
The following AWS IoT API actions are used to read or modify thing data. Devices that connect through an unauthenticated Amazon Cognito identity pool should not be given permission to perform these actions.
+ `DescribeThing`
+ `ListJobExecutionsForThing`
+ `ListThingGroupsForThing`
+ `ListThingPrincipals`
**Example**
+ noncompliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowIoTThingOperations",
"Effect": "Allow",
"Action": [
"iot:DescribeThing",
"iot:ListJobExecutionsForThing",
"iot:ListThingGroupsForThing",
"iot:ListThingPrincipals"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/name-of-thing"
]
}
]
}
```
------
This allows the device to perform the specified actions even though it is granted for one thing only.
## Manage non-things
Devices that connect through an unauthenticated Amazon Cognito identity pool should not be given permission to perform AWS IoT API actions other than those discussed in these sections. You can manage your account with an application that connects through an unauthenticated Amazon Cognito identity pool by creating a separate identity pool not used by devices.
## Subscribe/publish to MQTT topics
MQTT messages are sent through the AWS IoT message broker and are used by devices to perform many actions, including accessing and modifying shadow state and job execution state. A policy that grants permission to a device to connect, publish, or subscribe to MQTT messages should restrict these actions to specific resources as follows:
**Connect**
+ noncompliant:
```
arn:aws:iot:region:account-id:client/*
```
The wildcard \$1 allows any device to connect to AWS IoT.
```
arn:aws:iot:region:account-id:client/${iot:ClientId}
```
Unless `iot:Connection.Thing.IsAttached` is set to true in the condition keys, this is equivalent to the wildcard \$1 in the previous example.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/${iot:Connection.Thing.ThingName}"
]
}
]
}
```
------
The resource specification contains a variable that matches the device name used to connect. The condition statement further restricts the permission by checking that the certificate used by the MQTT client matches that attached to the thing with the name used.
**Publish**
+ noncompliant:
```
arn:aws:iot:region:account-id:topic/$aws/things/*/shadow/update
```
This allows the device to update the shadow of any device (\$1 = all devices).
```
arn:aws:iot:region:account-id:topic/$aws/things/*
```
This allows the device to read, update, or delete the shadow of any device.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
]
}
]
}
```
------
The resource specification contains a wildcard, but it only matches any shadow-related topic for the device whose thing name is used to connect.
**Subscribe**
+ noncompliant:
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
This allows the device to subscribe to reserved shadow or job topics for all devices.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
The same as the previous example, but using the \$1 wildcard.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/+/shadow/update
```
This allows the device to see shadow updates on any device (\$1 = all devices).
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/jobs/*"
]
}
]
}
```
------
The resource specifications contain wildcards, but they only match any shadow-related topic and any job-related topic for the device whose thing name is used to connect.
**Receive**
+ compliant:
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
This is allowed because the device can receive messages only from topics on which it has permission to subscribe.
## Read/modify shadow or job data
A policy that grants permission to a device to perform an API action to access or modify device shadows or job execution data should restrict these actions to specific resources. The following are the API actions:
+ `DeleteThingShadow`
+ `GetThingShadow`
+ `UpdateThingShadow`
+ `DescribeJobExecution`
+ `GetPendingJobExecutions`
+ `StartNextPendingJobExecutio`n
+ `UpdateJobExecution`
**Example**
+ noncompliant:
```
arn:aws:iot:region:account-id:thing/*
```
This allows the device to perform the specified action on any thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DeleteThingShadow",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iotjobsdata:DescribeJobExecution",
"iotjobsdata:GetPendingJobExecutions",
"iotjobsdata:StartNextPendingJobExecution",
"iotjobsdata:UpdateJobExecution"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing1",
"arn:aws:iot:us-east-1:123456789012:thing/MyThing2"
]
}
]
}
```
------
This allows the device to perform the specified actions on two things only.
# Authenticated Cognito role overly permissive
A policy attached to an authenticated Amazon Cognito identity pool role is considered too permissive because it grants permission to perform the following AWS IoT actions:
+ Manage or modify things.
+ Manage non-thing related data or resources.
Or, because it grants permission to perform the following AWS IoT actions on a broad set of devices:
+ Read thing administrative data.
+ Use MQTT to connect/publish/subscribe to reserved topics (including shadow or job execution data).
+ Use API commands to read or modify shadow or job execution data.
In general, devices that connect using an authenticated Amazon Cognito identity pool role should have only limited permission to read thing-specific administrative data, publish and subscribe to thing-specific MQTT topics, or use the API commands to read and modify thing-specific data related to shadow or job execution data.
This check appears as `AUTHENTICATED_COGNITO_ROLE_OVERLY_PERMISSIVE_CHECK` in the CLI and API.
Severity: **Critical**
## Details
For this check, AWS IoT Device Defender audits all Amazon Cognito identity pools that have been used to connect to the AWS IoT message broker during the 31 days before the audit execution. All Amazon Cognito identity pools from which either an authenticated or unauthenticated Amazon Cognito identity connected are included in the audit.
The following reason codes are returned when this check finds a noncompliant authenticated Amazon Cognito identity pool role:
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1IOT\$1THING\$1ADMIN\$1READ\$1ACTIONS
+ ALLOWS\$1ACCESS\$1TO\$1IOT\$1NON\$1THING\$1ADMIN\$1ACTIONS
+ ALLOWS\$1ACCESS\$1TO\$1IOT\$1THING\$1ADMIN\$1WRITE\$1ACTIONS
## Why it matters
If an authenticated identity is compromised, it can use administrative actions to modify account settings, delete resources, or gain access to sensitive data.
## How to fix it
A policy attached to an authenticated Amazon Cognito identity pool role should grant only those permissions required for a device to do its job. We recommend the following steps:
1. Create a new compliant role.
1. Create a Amazon Cognito identity pool and attach the compliant role to it.
1. Verify that your identities can access AWS IoT using the new pool.
1. After verification is complete, attach the role to the Amazon Cognito identity pool that was flagged as noncompliant.
You can also use mitigation actions to:
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
## Manage or modify things
The following AWS IoT API actions are used to manage or modify things so permission to perform these should not be granted to devices connecting through an authenticated Amazon Cognito identity pool:
+ `AddThingToThingGroup`
+ `AttachThingPrincipal`
+ `CreateThing`
+ `DeleteThing`
+ `DetachThingPrincipal`
+ `ListThings`
+ `ListThingsInThingGroup`
+ `RegisterThing`
+ `RemoveThingFromThingGroup`
+ `UpdateThing`
+ `UpdateThingGroupsForThing`
Any role that grants permission to perform these actions on even a single resource is considered noncompliant.
## Manage non-things
Devices that connect through an authenticated Amazon Cognito identity pool should not be given permission to perform AWS IoT API actions other than those discussed in these sections. To manage your account with an application that connects through an authenticated Amazon Cognito identity pool, create a separate identity pool not used by devices.
## Read thing administrative data
The following AWS IoT API actions are used to read thing data, so devices that connect through an authenticated Amazon Cognito identity pool should be given permission to perform these on a limited set of things only:
+ `DescribeThing`
+ `ListJobExecutionsForThing`
+ `ListThingGroupsForThing`
+ `ListThingPrincipals`
+ noncompliant:
```
arn:aws:iot:region:account-id:thing/*
```
This allows the device to perform the specified action on any thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeThing",
"iot:ListJobExecutionsForThing",
"iot:ListThingGroupsForThing",
"iot:ListThingPrincipals"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing"
]
}
]
}
```
------
This allows the device to perform the specified actions on only one thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeThing",
"iot:ListJobExecutionsForThing",
"iot:ListThingGroupsForThing",
"iot:ListThingPrincipals"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing*"
]
}
]
}
```
------
This is compliant because, although the resource is specified with a wildcard (\$1), it is preceded by a specific string, and that limits the set of things accessed to those with names that have the given prefix.
+ noncompliant:
```
arn:aws:iot:region:account-id:thing/*
```
This allows the device to perform the specified action on any thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeThing",
"iot:ListJobExecutionsForThing",
"iot:ListThingGroupsForThing",
"iot:ListThingPrincipals"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing"
]
}
]
}
```
------
This allows the device to perform the specified actions on only one thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeThing",
"iot:ListJobExecutionsForThing",
"iot:ListThingGroupsForThing",
"iot:ListThingPrincipals"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing*"
]
}
]
}
```
------
This is compliant because, although the resource is specified with a wildcard (\$1), it is preceded by a specific string, and that limits the set of things accessed to those with names that have the given prefix.
## Subscribe/publish to MQTT topics
MQTT messages are sent through the AWS IoT message broker and are used by devices to perform many different actions, including accessing and modifying shadow state and job execution state. A policy that grants permission to a device to connect, publish, or subscribe to MQTT messages should restrict these actions to specific resources as follows:
**Connect**
+ noncompliant:
```
arn:aws:iot:region:account-id:client/*
```
The wildcard \$1 allows any device to connect to AWS IoT.
```
arn:aws:iot:region:account-id:client/${iot:ClientId}
```
Unless `iot:Connection.Thing.IsAttached` is set to true in the condition keys, this is equivalent to the wildcard \$1 in the previous example.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/${iot:Connection.Thing.ThingName}"
]
}
]
}
```
------
The resource specification contains a variable that matches the device name used to connect, and the condition statement further restricts the permission by checking that the certificate used by the MQTT client matches that attached to the thing with the name used.
**Publish**
+ noncompliant:
```
arn:aws:iot:region:account-id:topic/$aws/things/*/shadow/update
```
This allows the device to update the shadow of any device (\$1 = all devices).
```
arn:aws:iot:region:account-id:topic/$aws/things/*
```
This allows the device to read/update/delete the shadow of any device.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
]
}
]
}
```
------
The resource specification contains a wildcard, but it only matches any shadow-related topic for the device whose thing name is used to connect.
**Subscribe**
+ noncompliant:
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
This allows the device to subscribe to reserved shadow or job topics for all devices.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/#
```
The same as the previous example, but using the \$1 wildcard.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/+/shadow/update
```
This allows the device to see shadow updates on any device (\$1 = all devices).
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/jobs/*"
]
}
]
}
```
------
The resource specifications contain wildcards, but they only match any shadow-related topic and any job-related topic for the device whose thing name is used to connect.
**Receive**
+ compliant:
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
This is compliant because the device can receive messages only from topics on which it has permission to subscribe.
## Read or modify shadow or job data
A policy that grants permission to a device to perform an API action to access or modify device shadows or job execution data should restrict these actions to specific resources. The following are the API actions:
+ `DeleteThingShadow`
+ `GetThingShadow`
+ `UpdateThingShadow`
+ `DescribeJobExecution`
+ `GetPendingJobExecutions`
+ `StartNextPendingJobExecution`
+ `UpdateJobExecution`
**Examples**
+ noncompliant:
```
arn:aws:iot:region:account-id:thing/*
```
This allows the device to perform the specified action on any thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DeleteThingShadow",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:DescribeJobExecution",
"iotjobsdata:DescribeJobExecution",
"iotjobsdata:UpdateJobExecution"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing1",
"arn:aws:iot:us-east-1:123456789012:thing/MyThing2"
]
}
]
}
```
------
This allows the device to perform the specified actions on only two things.
# AWS IoT policies overly permissive
An AWS IoT policy gives permissions that are too broad or unrestricted. It grants permission to send or receive MQTT messages for a broad set of devices, or grants permission to access or modify shadow and job execution data for a broad set of devices.
In general, a policy for a device should grant access to resources associated with just that device and no or very few other devices. With some exceptions, using a wildcard (for example, "\$1") to specify resources in such a policy is considered too broad or unrestricted.
This check appears as `IOT_POLICY_OVERLY_PERMISSIVE_CHECK` in the CLI and API.
Severity: **Critical**
## Details
The following reason code is returned when this check finds a noncompliant AWS IoT policy:
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1IOT\$1DATA\$1PLANE\$1ACTIONS
## Why it matters
A certificate, Amazon Cognito identity, or thing group with an overly permissive policy can, if compromised, impact the security of your entire account. An attacker could use such broad access to read or modify shadows, jobs, or job executions for all your devices. Or an attacker could use a compromised certificate to connect malicious devices or launch a DDOS attack on your network.
## How to fix it
Follow these steps to fix any noncompliant policies attached to things, thing groups, or other entities:
1. Use [CreatePolicyVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePolicyVersion.html) to create a new, compliant version of the policy. Set the `setAsDefault` flag to true. (This makes this new version operative for all entities that use the policy.)
1. Use [ListTargetsForPolicy](https://docs.aws.amazon.com/iot/latest/apireference/API_ListTargetsForPolicy.html) to get a list of targets (certificates, thing groups) that the policy is attached to and determine which devices are included in the groups or which use the certificates to connect.
1. Verify that all associated devices are able to connect to AWS IoT. If a device is unable to connect, use [ SetPolicyVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_SetPolicyVersion.html) to roll back the default policy to the previous version, revise the policy, and try again.
You can use mitigation actions to:
+ Apply the `REPLACE_DEFAULT_POLICY_VERSION` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
Use [AWS IoT Core policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-variables.html) to dynamically reference AWS IoT resources in your policies.
## MQTT permissions
MQTT messages are sent through the AWS IoT message broker and are used by devices to perform many actions, including accessing and modifying shadow state and job execution state. A policy that grants permission to a device to connect, publish, or subscribe to MQTT messages should restrict these actions to specific resources as follows:
**Connect**
+ noncompliant:
```
arn:aws:iot:region:account-id:client/*
```
The wildcard \$1 allows any device to connect to AWS IoT.
```
arn:aws:iot:region:account-id:client/${iot:ClientId}
```
Unless `iot:Connection.Thing.IsAttached` is set to true in the condition keys, this is equivalent to the wildcard \$1 as in the previous example.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:client/${iot:Connection.Thing.ThingName}"
]
}
]
}
```
------
The resource specification contains a variable that matches the device name used to connect. The condition statement further restricts the permission by checking that the certificate used by the MQTT client matches that attached to the thing with the name used.
**Publish**
+ noncompliant:
```
arn:aws:iot:region:account-id:topic/$aws/things/*/shadow/update
```
This allows the device to update the shadow of any device (\$1 = all devices).
```
arn:aws:iot:region:account-id:topic/$aws/things/*
```
This allows the device to read, update, or delete the shadow of any device.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
]
}
]
}
```
------
The resource specification contains a wildcard, but it only matches any shadow-related topic for the device whose thing name is used to connect.
**Subscribe**
+ noncompliant:
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
This allows the device to subscribe to reserved shadow or job topics for all devices.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/*
```
The same as the previous example, but using the \$1 wildcard.
```
arn:aws:iot:region:account-id:topicfilter/$aws/things/+/shadow/update
```
This allows the device to see shadow updates on any device (\$1 = all devices).
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/jobs/*"
]
}
]
}
```
------
The resource specifications contain wildcards, but they only match any shadow-related topic and any job-related topic for the device whose thing name is used to connect.
**Receive**
+ compliant:
```
arn:aws:iot:region:account-id:topic/$aws/things/*
```
This is compliant because the device can only receive messages from topics on which it has permission to subscribe.
## Shadow and job permissions
A policy that grants permission to a device to perform an API action to access or modify device shadows or job execution data should restrict these actions to specific resources. The following are the API actions:
+ `DeleteThingShadow`
+ `GetThingShadow`
+ `UpdateThingShadow`
+ `DescribeJobExecution`
+ `GetPendingJobExecutions`
+ `StartNextPendingJobExecution`
+ `UpdateJobExecution`
**Examples**
+ noncompliant:
```
arn:aws:iot:region:account-id:thing/*
```
This allows the device to perform the specified action on any thing.
+ compliant:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DeleteThingShadow",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iotjobsdata:DescribeJobExecution",
"iotjobsdata:GetPendingJobExecutions",
"iotjobsdata:StartNextPendingJobExecution",
"iotjobsdata:UpdateJobExecution"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/MyThing1",
"arn:aws:iot:us-east-1:123456789012:thing/MyThing2"
]
}
]
}
```
------
This allows the device to perform the specified actions on only two things.
# AWS IoT policy potentially misconfigured
An AWS IoT policy was identified as potentially misconfigured. Misconfigured policies, including overly permissive policies, can cause security incidents like allowing devices access to unintended resources.
The **AWS IoT policy potentially misconfigured** check is a warning for you to make sure that only intended actions are allowed before updating the policy.
In the CLI and API, this check appears as `IOT_POLICY_POTENTIAL_MISCONFIGURATION_CHECK`.
Severity: **Medium**
## Details
AWS IoT returns the following reason code when this check finds a potentially misconfigured AWS IoT policy:
+ POLICY\$1CONTAINS\$1MQTT\$1WILDCARDS\$1IN\$1DENY\$1STATEMENT
+ TOPIC\$1FILTERS\$1INTENDED\$1TO\$1DENY\$1ALLOWED\$1USING\$1WILDCARDS
## Why it matters
Misconfigured policies can lead to unintended consequences by providing more permissions to devices than required. We recommend careful consideration of the policy to limit access to resources and prevent security threats.
### Policy contains MQTT wildcards in deny statement example
The **AWS IoT policy potentially misconfigured** check inspects for MQTT wildcard characters (`+` or `#`) in deny statements. Wildcards are treated as literal strings by AWS IoT policies and can make the policy overly permissive.
The following example is intended to deny subscribing to topics related to `building/control_room` by using the MQTT wildcard `#` in policies. However, MQTT wildcards don't have a wildcard meaning in AWS IoT policies and devices can subscribe to `building/control_room/data1`.
The **AWS IoT policy potentially misconfigured** check will flag this policy with reason code `POLICY_CONTAINS_MQTT_WILDCARDS_IN_DENY_STATEMENT`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/control_room/#"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/*"
}
]
}
```
------
The following is an example of a properly configured policy. Devices don't have permission to subscribe to subtopics of `building/control_room/` and don't have permissions to receive messages from subtopics of `building/control_room/`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/control_room/*"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/control_room/*"
}
]
}
```
------
### Topic filters intended to deny allowed using wildcards example
The following example policy is intended to deny subscribing to topics related to `building/control_room` by denying the resource `building/control_room/*`. However, devices can send requests to subscribe to `building/#` and receive messages from all topics related to `building`, including `building/control_room/data1`.
The **AWS IoT policy potentially misconfigured** check will flag this policy with reason code `TOPIC_FILTERS_INTENDED_TO_DENY_ALLOWED_USING_WILDCARDS`.
The following example policy has permissions to receive message on `building/control_room topics`:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/control_room/*"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/*"
}
]
}
```
------
The following is an example of a properly configured policy. Devices don't have permission to subscribe to subtopics of `building/control_room/` and don't have permissions to receive messages from subtopics of `building/control_room/`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/building/control_room/*"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/*"
},
{
"Effect": "Deny",
"Action": "iot:Receive",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/building/control_room/*"
}
]
}
```
------
**Note**
This check might report false positives. We recommend that you evaluate any flagged policies and mark false positives resources using audit suppressions.
## How to fix it
This check flags potentially misconfigured policies so there might be false positives. Mark any false positives using [audit suppressions](audit-finding-suppressions.md) so they aren't flagged in the future.
You can also follow these steps to fix any noncompliant policies attached to things, thing groups, or other entities:
1. Use [CreatePolicyVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePolicyVersion.html) to create a new, compliant version of the policy. Set the `setAsDefault` flag to true. (This makes this new version operative for all entities that use the policy.)
For examples of creating AWS IoT policies for common use cases, see [Publish/Subscribe policy examples](https://docs.aws.amazon.com/iot/latest/developerguide/pub-sub-policy.html) in the *AWS IoT Core Developer Guide*.
1. Verify that all associated devices are able to connect to AWS IoT. If a device is unable to connect, use [ SetPolicyVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_SetPolicyVersion.html) to roll back the default policy to the previous version, revise the policy, and try again.
You can use mitigation actions to:
+ Apply the `REPLACE_DEFAULT_POLICY_VERSION` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
Use [IoT Core policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-variables.html) in the *AWS IoT Core Developer Guide* to dynamically reference AWS IoT resources in your policies.
# Role alias overly permissive
AWS IoT role alias provides a mechanism for connected devices to authenticate to AWS IoT using X.509 certificates and then obtain short-lived AWS credentials from an IAM role that is associated with an AWS IoT role alias. The permissions for these credentials must be scoped down using access policies with authentication context variables. If your policies are not configured correctly, you could leave yourself exposed to an escalation of privilege attack. This audit check ensures that the temporary credentials provided by AWS IoT role aliases are not overly permissive.
This check is triggered if one of the following conditions are found:
+ The policy provides administrative permissions to any services used in the past year by this role alias (for example, "iot:\$1", "dynamodb:\$1", "iam:\$1", and so on).
+ The policy provides broad access to thing metadata actions, access to restricted AWS IoT actions, or broad access to AWS IoT data plane actions.
+ The policy provides access to security auditing services such as "iam", "cloudtrail", "guardduty", "inspector", or "trustedadvisor".
This check appears as `IOT_ROLE_ALIAS_OVERLY_PERMISSIVE_CHECK` in the CLI and API.
Severity: **Critical**
## Details
The following reason codes are returned when this check finds a noncompliant IoT policy:
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1USED\$1SERVICES
+ ALLOWS\$1ACCESS\$1TO\$1SECURITY\$1AUDITING\$1SERVICES
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1IOT\$1THING\$1ADMIN\$1READ\$1ACTIONS
+ ALLOWS\$1ACCESS\$1TO\$1IOT\$1NON\$1THING\$1ADMIN\$1ACTIONS
+ ALLOWS\$1ACCESS\$1TO\$1IOT\$1THING\$1ADMIN\$1WRITE\$1ACTIONS
+ ALLOWS\$1BROAD\$1ACCESS\$1TO\$1IOT\$1DATA\$1PLANE\$1ACTIONS
## Why it matters
By limiting permissions to those that are required for a device to perform its normal operations, you reduce the risks to your account if a device is compromised.
## How to fix it
Follow these steps to fix any noncompliant policies attached to things, thing groups, or other entities:
1. Follow the steps in [Authorizing direct calls to AWS services using AWS IoT Core credential provider](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) to apply a more restrictive policy to your role alias.
You can use mitigation actions to:
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom action in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# Role alias allows access to unused services
AWS IoT role alias provides a mechanism for connected devices to authenticate to AWS IoT using X.509 certificates and then obtain short-lived AWS credentials from an IAM role that is associated with an AWS IoT role alias. The permissions for these credentials must be scoped down using access policies with authentication context variables. If your policies are not configured correctly, you could leave yourself exposed to an escalation of privilege attack. This audit check ensures that the temporary credentials provided by AWS IoT role aliases are not overly permissive.
This check is triggered if the role alias has access to services that haven't been used for the AWS IoT device in the last year. For example, the audit reports if you have an IAM role linked to the role alias that has only used AWS IoT in the past year but the policy attached to the role also grants permission to `"iam:getRole"` and `"dynamodb:PutItem"`.
This check appears as `IOT_ROLE_ALIAS_ALLOWS_ACCESS_TO_UNUSED_SERVICES_CHECK` in the CLI and API.
Severity: **Medium**
## Details
The following reason codes are returned when this check finds a noncompliant AWS IoT policy:
+ ALLOWS\$1ACCESS\$1TO\$1UNUSED\$1SERVICES
## Why it matters
By limiting permissions to those services that are required for a device to perform its normal operations, you reduce the risks to your account if a device is compromised.
## How to fix it
Follow these steps to fix any noncompliant policies attached to things, thing groups, or other entities:
1. Follow the steps in [Authorizing direct calls to AWS services using AWS IoT Core credential provider](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) to apply a more restrictive policy to your role alias.
You can use mitigation actions to:
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom action in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# CA certificate expiring
A CA certificate is expiring within 30 days or has expired.
This check appears as `CA_CERTIFICATE_EXPIRING_CHECK` in the CLI and API.
Severity: **Medium**
## Details
This check applies to CA certificates that are ACTIVE or PENDING\$1TRANSFER.
The following reason codes are returned when this check finds a noncompliant CA certificate:
+ CERTIFICATE\$1APPROACHING\$1EXPIRATION
+ CERTIFICATE\$1PAST\$1EXPIRATION
## Why it matters
An expired CA certificate should not be used to sign new device certificates.
## How to fix it
Consult your security best practices for how to proceed. You might want to:
1. Register a new CA certificate with AWS IoT.
1. Verify that you are able to sign device certificates using the new CA certificate.
1. Use [UpdateCACertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCACertificate.html) to mark the old CA certificate as INACTIVE in AWS IoT. You can also use mitigation actions to do the following:
+ Apply the `UPDATE_CA_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# Conflicting MQTT client IDs
Multiple devices connect using the same client ID.
This check appears as `CONFLICTING_CLIENT_IDS_CHECK` in the CLI and API.
Severity: **High**
## Details
Multiple connections were made using the same client ID, causing an already connected device to be disconnected. The MQTT specification allows only one active connection per client ID, so when another device connects using the same client ID, it knocks the previous one off the connection.
When performed as part of an on-demand audit, this check looks at how client IDs were used to connect during the 31 days prior to the start of the audit. For scheduled audits, this check looks at data from the last time the audit was run to the time this instance of the audit started. If you have taken steps to mitigate this condition during the time checked, note when the connections/disconnections were made to determine if the problem persists.
The following reason codes are returned when this check finds noncompliance:
+ DUPLICATE\$1CLIENT\$1ID\$1ACROSS\$1CONNECTIONS
The findings returned by this check also include the client ID used to connect, principal IDs, and disconnect times. The most recent results are listed first.
## Why it matters
Devices with conflicting IDs are forced to constantly reconnect, which might result in lost messages or leave a device unable to connect.
This might indicate that a device or a device's credentials have been compromised, and might be part of a DDoS attack. It is also possible that devices are not configured correctly in the account or a device has a bad connection and is forced to reconnect several times per minute.
## How to fix it
Register each device as a unique thing in AWS IoT, and use the thing name as the client ID to connect. Or use a UUID as the client ID when connecting the device over MQTT. You can also use mitigation actions to:
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# Device certificate expiring
A device certificate is expiring within the configured threshold period or has expired. The certificate expiration check threshold can be configured between 30 days (minimum) and 3652 days (10 years, maximum) with a default value of 30 days.
This check appears as `DEVICE_CERTIFICATE_EXPIRING_CHECK` in the CLI and API.
Severity: **Medium**
## Details
This check applies to device certificates that are ACTIVE or PENDING\$1TRANSFER.
The following reason codes are returned when this check finds a noncompliant device certificate:
+ CERTIFICATE\$1APPROACHING\$1EXPIRATION
+ CERTIFICATE\$1PAST\$1EXPIRATION
## Why it matters
A device certificate should not be used after it expires.
## Configuring the Device certificate expiring check
This configuration enables you to monitor and receive alerts for certificates that are approaching their expiration date across your device fleet. For example, if you want to be notified when certificates are within 30 days of expiration, you can configure the check as follows:
```
{
"roleArn": "your-audit-role-arn",
"auditCheckConfigurations": {
"DEVICE_CERTIFICATE_EXPIRING_CHECK": {
"enabled": true,
"configuration": {
"CERT_EXPIRATION_THRESHOLD_IN_DAYS": "30"
}
}
}
}
```
## How to fix it
Consult your security best practices for how to proceed. You might want to:
1. Provision a new certificate and attach it to the device.
1. Verify that the new certificate is valid and the device is able to use it to connect.
1. Use [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to mark the old certificate as INACTIVE in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_DEVICE_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `ADD_THINGS_TO_THING_GROUP` mitigation action to add the device to a group where you can take action on it.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Detach the old certificate from the device. (See [DetachThingPrincipal](https://docs.aws.amazon.com/iot/latest/apireference/API_DetachThingPrincipal.html).)
# Device certificate age check
This audit check alerts you when a device certificate has been active for a number of days greater than or equal to the number you specify. This check helps you stay informed about your certificates’ status, enabling timely action on a periodic basis, regardless of when the certificate reaches the end of its lifespan, improving security by reducing the risk of certificate compromise.
The certificate age check threshold can be configured between 30 days (minimum) and 3652 days (10 years, maximum), with a default value of 365 days.
This check appears as `DEVICE_CERTIFICATE_AGE_CHECK` in the CLI and API. This check is disabled by default Severity: **Low**
## Details
This check applies to device certificates that are ACTIVE or PENDING\$1TRANSFER. The following reason codes are returned when this check finds a noncompliant device certificate:
+ CERTIFICATE\$1PAST\$1AGE\$1THRESHOLD
## Configuring the device certificate age check
This configuration allows you to tailor certificate rotation alerts to the specific needs of your fleet, helping you maintain a strong security posture across all devices. You can configure this check using the `UpdateAccountAuditConfiguration` API. For example, if you want to be alerted when certificates have been active for more than 365 days, you can configure the check as follows:
```
{
"roleArn": "your-audit-role-arn",
"auditCheckConfigurations": {
"DEVICE_CERTIFICATE_AGE_CHECK": {
"enabled": true,
"configuration": {
"CERT_AGE_THRESHOLD_IN_DAYS": "365"
}
}
}
}
```
# Revoked device certificate still active
A revoked device certificate is still active.
This check appears as `REVOKED_DEVICE_CERTIFICATE_STILL_ACTIVE_CHECK` in the CLI and API.
Severity: **Medium**
## Details
A device certificate is in its CA's [certificate revocation list](https://en.wikipedia.org/wiki/Certificate_revocation_list), but it is still active in AWS IoT.
This check applies to device certificates that are ACTIVE or PENDING\$1TRANSFER.
The following reason codes are returned when this check finds noncompliance:
+ CERTIFICATE\$1REVOKED\$1BY\$1ISSUER
## Why it matters
A device certificate is usually revoked because it has been compromised. It is possible that it has not yet been revoked in AWS IoT due to an error or oversight.
## How to fix it
Verify that the device certificate has not been compromised. If it has, follow your security best practices to mitigate the situation. You might want to:
1. Provision a new certificate for the device.
1. Verify that the new certificate is valid and the device is able to use it to connect.
1. Use [UpdateCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCertificate.html) to mark the old certificate as REVOKED in AWS IoT. You can also use mitigation actions to:
+ Apply the `UPDATE_DEVICE_CERTIFICATE` mitigation action on your audit findings to make this change.
+ Apply the `ADD_THINGS_TO_THING_GROUP` mitigation action to add the device to a group where you can take action on it.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
1. Detach the old certificate from the device. (See [DetachThingPrincipal](https://docs.aws.amazon.com/iot/latest/apireference/API_DetachThingPrincipal.html).)
# Logging disabled
AWS IoT logs are not enabled in Amazon CloudWatch. Verifies both V1 and V2 logging.
This check appears as `LOGGING_DISABLED_CHECK` in the CLI and API.
Severity: **Low**
## Details
The following reason codes are returned when this check finds noncompliance:
+ LOGGING\$1DISABLED
## Why it matters
AWS IoT logs in CloudWatch provide visibility into behaviors in AWS IoT, including authentication failures and unexpected connects and disconnects that might indicate that a device has been compromised.
## How to fix it
Enable AWS IoT logs in CloudWatch. See [Logging and Monitoring](https://docs.aws.amazon.com/iot/latest/developerguide/security-logging.html) in the *AWS IoT Core Developer Guide*. You can also use mitigation actions to:
+ Apply the `ENABLE_IOT_LOGGING` mitigation action on your audit findings to make this change.
+ Apply the `PUBLISH_FINDINGS_TO_SNS` mitigation action if you want to implement a custom response in response to the Amazon SNS message.
For more information, see [Mitigation actions](dd-mitigation-actions.md).
# Audit commands
## Manage audit settings
Use `UpdateAccountAuditConfiguration` to configure audit settings for your account. This command allows you to enable those checks you want to be available for audits, set up optional notifications, and configure permissions.
Check these settings with `DescribeAccountAuditConfiguration`.
Use `DeleteAccountAuditConfiguration` to delete your audit settings. This restores all default values, and effectively disables audits because all checks are disabled by default.
### UpdateAccountAuditConfiguration
Configures or reconfigures the Device Defender audit settings for this account. Settings include how audit notifications are sent and which audit checks are enabled or disabled.
**Synopsis**
```
aws iot update-account-audit-configuration \
[--role-arn ] \
[--audit-notification-target-configurations ] \
[--audit-check-configurations ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"roleArn": "string",
"auditNotificationTargetConfigurations": {
"string": {
"targetArn": "string",
"roleArn": "string",
"enabled": "boolean"
}
},
"auditCheckConfigurations": {
"string": {
"enabled": "boolean"
}
}
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| roleArn | string length- max:2048 min:20 | The ARN of the role that grants permission to AWS IoT to access information about your devices, policies, certificates, and other items when performing an audit. |
| auditNotificationTargetConfigurations | map | Information about the targets to which audit notifications are sent. |
| targetArn | string | The ARN of the target (SNS topic) to which audit notifications are sent. |
| roleArn | string length- max:2048 min:20 | The ARN of the role that grants permission to send notifications to the target. |
| enabled | boolean | True if notifications to the target are enabled. |
| auditCheckConfigurations | map | Specifies which audit checks are enabled and disabled for this account. Use `DescribeAccountAuditConfiguration` to see the list of all checks, including those that are currently enabled. Some data collection might start immediately when certain checks are enabled. When a check is disabled, any data collected so far in relation to the check is deleted. You cannot disable a check if it is used by any scheduled audit. You must first delete the check from the scheduled audit or delete the scheduled audit itself. On the first call to `UpdateAccountAuditConfiguration`, this parameter is required and must specify at least one enabled check. |
| enabled | boolean | True if this audit check is enabled for this account. |
| configuration | map | (Optional) custom configurations for specific audit checks, such as the `CERT_AGE_THRESHOLD_IN_DAYS` and `CERT_EXPIRATION_THRESHOLD_IN_DAYS`, allowing you to define when you want to be alerted about certificate age and impending expiration. |
Output
None
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### DescribeAccountAuditConfiguration
Gets information about the Device Defender audit settings for this account. Settings include how audit notifications are sent and which audit checks are enabled or disabled.
**Synopsis**
```
aws iot describe-account-audit-configuration \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
}
```
Output
```
{
"roleArn": "string",
"auditNotificationTargetConfigurations": {
"string": {
"targetArn": "string",
"roleArn": "string",
"enabled": "boolean"
}
},
"auditCheckConfigurations": {
"string": {
"enabled": "boolean"
}
}
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| roleArn | string length- max:2048 min:20 | The ARN of the role that grants permission to AWS IoT to access information about your devices, policies, certificates, and other items when performing an audit. On the first call to `UpdateAccountAuditConfiguration`, this parameter is required. |
| auditNotificationTargetConfigurations | map | Information about the targets to which audit notifications are sent for this account. |
| targetArn | string | The ARN of the target (SNS topic) to which audit notifications are sent. |
| roleArn | string length- max:2048 min:20 | The ARN of the role that grants permission to send notifications to the target. |
| enabled | boolean | True if notifications to the target are enabled. |
| auditCheckConfigurations | map | Which audit checks are enabled and disabled for this account. |
| enabled | boolean | True if this audit check is enabled for this account. |
| configuration | map | (Optional) provides specific configurations for certain audit checks, such as the maximum allowed age for certificates or the number of days before expiration when an alert should be triggered. |
**Errors**
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### DeleteAccountAuditConfiguration
Restores the default settings for Device Defender audits for this account. Any configuration data you entered is deleted and all audit checks are reset to disabled.
**Synopsis**
```
aws iot delete-account-audit-configuration \
[--delete-scheduled-audits | --no-delete-scheduled-audits] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"deleteScheduledAudits": "boolean"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| deleteScheduledAudits | boolean | If true, all scheduled audits are deleted. |
Output
None
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ResourceNotFoundException`
The specified resource does not exist.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
## Schedule audits
Use `CreateScheduledAudit` to create one or more scheduled audits. This command allows you to specify the checks you want to perform during an audit and how often the audit should be run.
Keep track of your scheduled audits with `ListScheduledAudits` and `DescribeScheduledAudit`.
Change an existing scheduled audit with `UpdateScheduledAudit` or delete it with `DeleteScheduledAudit`.
### CreateScheduledAudit
Creates a scheduled audit that is run at a specified time interval.
**Synopsis**
```
aws iot create-scheduled-audit \
--frequency \
[--day-of-month ] \
[--day-of-week ] \
--target-check-names \
[--tags ] \
--scheduled-audit-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"frequency": "string",
"dayOfMonth": "string",
"dayOfWeek": "string",
"targetCheckNames": [
"string"
],
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"scheduledAuditName": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| frequency | string | How often the scheduled audit takes place. Can be one of DAILY, WEEKLY, BIWEEKLY, or MONTHLY. The actual start time of each audit is determined by the system. enum: DAILY \$1 WEEKLY \$1 BIWEEKLY \$1 MONTHLY |
| dayOfMonth | string pattern: ^([1-9]\$1[12][0-9]\$13[01])\$1\$1^LAST\$1 | The day of the month on which the scheduled audit takes place. Can be 1 through 31 or LAST. This field is required if the `frequency` parameter is set to MONTHLY. If days 29-31 are specified, and the month does not have that many days, the audit takes place on the LAST day of the month. |
| dayOfWeek | string | The day of the week on which the scheduled audit takes place. Can be one of SUN, MON, TUE,WED, THU, FRI, or SAT. This field is required if the `frequency` parameter is set to WEEKLY or BIWEEKLY. enum: SUN \$1 MON \$1 TUE \$1 WED \$1 THU \$1 FRI \$1 SAT |
| targetCheckNames | list member: AuditCheckName | Which checks are performed during the scheduled audit. Checks must be enabled for your account. (Use `DescribeAccountAuditConfiguration` to see the list of all checks, including those that are enabled or `UpdateAccountAuditConfiguration` to select which checks are enabled.) |
| tags | list member: Tag java class: java.util.List | Metadata that can be used to manage the scheduled audit. |
| Key | string | The tag's key. |
| Value | string | The tag's value. |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name you want to give to the scheduled audit. (Maximum of 128 characters) |
Output
```
{
"scheduledAuditArn": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| scheduledAuditArn | string | The ARN of the scheduled audit. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
`LimitExceededException`
A limit has been exceeded.
### ListScheduledAudits
Lists all of your scheduled audits.
**Synopsis**
```
aws iot list-scheduled-audits \
[--next-token ] \
[--max-results ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"nextToken": "string",
"maxResults": "integer"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| nextToken | string | The token for the next set of results. |
| maxResults | integer range- max:250 min:1 | The maximum number of results to return at one time. The default is 25. |
Output
```
{
"scheduledAudits": [
{
"scheduledAuditName": "string",
"scheduledAuditArn": "string",
"frequency": "string",
"dayOfMonth": "string",
"dayOfWeek": "string"
}
],
"nextToken": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| scheduledAudits | list member: ScheduledAuditMetadata java class: java.util.List | The list of scheduled audits. |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit. |
| scheduledAuditArn | string | The ARN of the scheduled audit. |
| frequency | string | How often the scheduled audit takes place. enum: DAILY \$1 WEEKLY \$1 BIWEEKLY \$1 MONTHLY |
| dayOfMonth | string pattern: ^([1-9]\$1[12][0-9]\$13[01])\$1\$1^LAST\$1 | The day of the month on which the scheduled audit is run (if the `frequency` is MONTHLY). If days 29-31 are specified, and the month does not have that many days, the audit takes place on the LAST day of the month. |
| dayOfWeek | string | The day of the week on which the scheduled audit is run (if the `frequency` is WEEKLY or BIWEEKLY). enum: SUN \$1 MON \$1 TUE \$1 WED \$1 THU \$1 FRI \$1 SAT |
| nextToken | string | A token that can be used to retrieve the next set of results, or `null` if there are no more results. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### DescribeScheduledAudit
Gets information about a scheduled audit.
**Synopsis**
```
aws iot describe-scheduled-audit \
--scheduled-audit-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"scheduledAuditName": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit whose information you want to get. |
Output
```
{
"frequency": "string",
"dayOfMonth": "string",
"dayOfWeek": "string",
"targetCheckNames": [
"string"
],
"scheduledAuditName": "string",
"scheduledAuditArn": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| frequency | string | How often the scheduled audit takes place. One of DAILY, WEEKLY, BIWEEKLY, or MONTHLY. The actual start time of each audit is determined by the system. enum: DAILY \$1 WEEKLY \$1 BIWEEKLY \$1 MONTHLY |
| dayOfMonth | string pattern: ^([1-9]\$1[12][0-9]\$13[01])\$1\$1^LAST\$1 | The day of the month on which the scheduled audit takes place. Can be 1 through 31 or LAST. If days 29-31 are specified, and the month does not have that many days, the audit takes place on the LAST day of the month. |
| dayOfWeek | string | The day of the week on which the scheduled audit takes place. One of SUN, MON, TUE, WED, THU, FRI, or SAT. enum: SUN \$1 MON \$1 TUE \$1 WED \$1 THU \$1 FRI \$1 SAT |
| targetCheckNames | list member: AuditCheckName | Which checks are performed during the scheduled audit. Checks must be enabled for your account. (Use `DescribeAccountAuditConfiguration` to see the list of all checks, including those that are enabled or use `UpdateAccountAuditConfiguration` to select which checks are enabled.) |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit. |
| scheduledAuditArn | string | The ARN of the scheduled audit. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ResourceNotFoundException`
The specified resource does not exist.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### UpdateScheduledAudit
Updates a scheduled audit, including which checks are performed and how often the audit takes place.
**Synopsis**
```
aws iot update-scheduled-audit \
[--frequency ] \
[--day-of-month ] \
[--day-of-week ] \
[--target-check-names ] \
--scheduled-audit-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"frequency": "string",
"dayOfMonth": "string",
"dayOfWeek": "string",
"targetCheckNames": [
"string"
],
"scheduledAuditName": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| frequency | string | How often the scheduled audit takes place. Can be one of DAILY, WEEKLY, BIWEEKLY, or MONTHLY. The actual start time of each audit is determined by the system. enum: DAILY \$1 WEEKLY \$1 BIWEEKLY \$1 MONTHLY |
| dayOfMonth | string pattern: ^([1-9]\$1[12][0-9]\$13[01])\$1\$1^LAST\$1 | The day of the month on which the scheduled audit takes place. Can be 1 through 31 or LAST. This field is required if the `frequency` parameter is set to MONTHLY. If days 29-31 are specified, and the month does not have that many days, the audit takes place on the LAST day of the month. |
| dayOfWeek | string | The day of the week on which the scheduled audit takes place. Can be one of SUN, MON, TUE, WED, THU, FRI, or SAT. This field is required if the `frequency` parameter is set to WEEKLY or BIWEEKLY. enum: SUN \$1 MON \$1 TUE \$1 WED \$1 THU \$1 FRI \$1 SAT |
| targetCheckNames | list member: AuditCheckName | Which checks are performed during the scheduled audit. Checks must be enabled for your account. (Use `DescribeAccountAuditConfiguration` to see the list of all checks, including those that are enabled or use `UpdateAccountAuditConfiguration` to select which checks are enabled.) |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit. (Maximum of 128 characters) |
Output
```
{
"scheduledAuditArn": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| scheduledAuditArn | string | The ARN of the scheduled audit. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ResourceNotFoundException`
The specified resource does not exist.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### DeleteScheduledAudit
Deletes a scheduled audit.
**Synopsis**
```
aws iot delete-scheduled-audit \
--scheduled-audit-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"scheduledAuditName": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit you want to delete. |
Output
None
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ResourceNotFoundException`
The specified resource does not exist.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
## Run an On-Demand audit
Use `StartOnDemandAuditTask` to specify the checks you want to perform and start an audit running right away.
### StartOnDemandAuditTask
Starts an on-demand Device Defender audit.
**Synopsis**
```
aws iot start-on-demand-audit-task \
--target-check-names \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"targetCheckNames": [
"string"
]
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| targetCheckNames | list member: AuditCheckName | Which checks are performed during the audit. The checks you specify must be enabled for your account or an exception occurs. Use `DescribeAccountAuditConfiguration` to see the list of all checks, including those that are enabled or use `UpdateAccountAuditConfiguration` to select which checks are enabled. |
Output
```
{
"taskId": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | The ID of the on-demand audit you started. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
`LimitExceededException`
A limit has been exceeded.
## Manage audit instances
Use `DescribeAuditTask` to get information about a specific audit instance. If it has already run, the results include which checks failed and which passed, those that the system was unable to complete, and if the audit is still in progress, those it is still working on.
Use `ListAuditTasks` to find the audits that were run during a specified time interval.
Use `CancelAuditTask` to halt an audit in progress.
### DescribeAuditTask
Gets information about a Device Defender audit.
**Synopsis**
```
aws iot describe-audit-task \
--task-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"taskId": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | The ID of the audit whose information you want to get. |
Output
```
{
"taskStatus": "string",
"taskType": "string",
"taskStartTime": "timestamp",
"taskStatistics": {
"totalChecks": "integer",
"inProgressChecks": "integer",
"waitingForDataCollectionChecks": "integer",
"compliantChecks": "integer",
"nonCompliantChecks": "integer",
"failedChecks": "integer",
"canceledChecks": "integer"
},
"scheduledAuditName": "string",
"auditDetails": {
"string": {
"checkRunStatus": "string",
"checkCompliant": "boolean",
"totalResourcesCount": "long",
"nonCompliantResourcesCount": "long",
"errorCode": "string",
"message": "string"
}
}
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| taskStatus | string | The status of the audit: one of IN\$1PROGRESS, COMPLETED, FAILED, or CANCELED. enum: IN\$1PROGRESS \$1 COMPLETED \$1 FAILED \$1 CANCELED |
| taskType | string | The type of audit: ON\$1DEMAND\$1AUDIT\$1TASK or SCHEDULED\$1AUDIT\$1TASK. enum: ON\$1DEMAND\$1AUDIT\$1TASK \$1 SCHEDULED\$1AUDIT\$1TASK |
| taskStartTime | timestamp | The time the audit started. |
| taskStatistics | TaskStatistics | Statistical information about the audit. |
| totalChecks | integer | The number of checks in this audit. |
| inProgressChecks | integer | The number of checks in progress. |
| waitingForDataCollectionChecks | integer | The number of checks waiting for data collection. |
| compliantChecks | integer | The number of checks that found compliant resources. |
| nonCompliantChecks | integer | The number of checks that found noncompliant resources. |
| failedChecks | integer | The number of checks. |
| canceledChecks | integer | The number of checks that did not run because the audit was canceled. |
| scheduledAuditName | string length- max:128 min:1 pattern: [a-zA-Z0-9\$1-]\$1 | The name of the scheduled audit (only if the audit was a scheduled audit). |
| auditDetails | map | Detailed information about each check performed during this audit. |
| checkRunStatus | string | The completion status of this check, one of IN\$1PROGRESS, WAITING\$1FOR\$1DATA\$1COLLECTION, CANCELED, COMPLETED\$1COMPLIANT, COMPLETED\$1NON\$1COMPLIANT, or FAILED. enum: IN\$1PROGRESS \$1 WAITING\$1FOR\$1DATA\$1COLLECTION \$1 CANCELED \$1 COMPLETED\$1COMPLIANT \$1 COMPLETED\$1NON\$1COMPLIANT \$1 FAILED |
| checkCompliant | boolean | True if the check completed and found all resources compliant. |
| totalResourcesCount | long | The number of resources on which the check was performed. |
| nonCompliantResourcesCount | long | The number of resources that the check found noncompliant. |
| errorCode | string | The code of any error encountered when performing this check during this audit. One of INSUFFICIENT\$1PERMISSIONS or AUDIT\$1CHECK\$1DISABLED. |
| message | string length- max:2048 | The message associated with any error encountered when performing this check during this audit. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ResourceNotFoundException`
The specified resource does not exist.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### ListAuditTasks
Lists the Device Defender audits that have been performed during a given time period.
**Synopsis**
```
aws iot list-audit-tasks \
--start-time \
--end-time \
[--task-type ] \
[--task-status ] \
[--next-token ] \
[--max-results ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"startTime": "timestamp",
"endTime": "timestamp",
"taskType": "string",
"taskStatus": "string",
"nextToken": "string",
"maxResults": "integer"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| startTime | timestamp | The beginning of the time period. Audit information is retained for a limited time (180 days). Requesting a start time prior to what is retained results in an `InvalidRequestException`. |
| endTime | timestamp | The end of the time period. |
| taskType | string | A filter to limit the output to the specified type of audit: can be one of ON\$1DEMAND\$1AUDIT\$1TASK or SCHEDULED\$1\$1AUDIT\$1TASK. enum: ON\$1DEMAND\$1AUDIT\$1TASK \$1 SCHEDULED\$1AUDIT\$1TASK |
| taskStatus | string | A filter to limit the output to audits with the specified completion status: can be one of IN\$1PROGRESS, COMPLETED, FAILED, or CANCELED. enum: IN\$1PROGRESS \$1 COMPLETED \$1 FAILED \$1 CANCELED |
| nextToken | string | The token for the next set of results. |
| maxResults | integer range- max:250 min:1 | The maximum number of results to return at one time. The default is 25. |
Output
```
{
"tasks": [
{
"taskId": "string",
"taskStatus": "string",
"taskType": "string"
}
],
"nextToken": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| tasks | list member: AuditTaskMetadata java class: java.util.List | The audits that were performed during the specified time period. |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | The ID of this audit. |
| taskStatus | string | The status of this audit: one of IN\$1PROGRESS, COMPLETED, FAILED, or CANCELED. enum: IN\$1PROGRESS \$1 COMPLETED \$1 FAILED \$1 CANCELED |
| taskType | string | The type of this audit: one of ON\$1DEMAND\$1AUDIT\$1TASK or SCHEDULED\$1AUDIT\$1TASK. enum: ON\$1DEMAND\$1AUDIT\$1TASK \$1 SCHEDULED\$1AUDIT\$1TASK |
| nextToken | string | A token that can be used to retrieve the next set of results, or `null` if there are no additional results. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
### CancelAuditTask
Cancels an audit that is in progress. The audit can be either scheduled or on-demand. If the audit is not in progress, an `InvalidRequestException` occurs.
**Synopsis**
```
aws iot cancel-audit-task \
--task-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"taskId": "string"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | The ID of the audit you want to cancel. You can only cancel an audit that is IN\$1PROGRESS. |
Output
None
**Errors**
`ResourceNotFoundException`
The specified resource does not exist.
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
## Check audit results
Use `ListAuditFindings` to see the results of an audit. You can filter the results by the type of check, a specific resource, or the time of the audit. You can use this information to mitigate any problems that were found.
You can define mitigation actions and apply them to the findings from your audit. For more information, see [Mitigation actions](dd-mitigation-actions.md).
### ListAuditFindings
Lists the findings (results) of a Device Defender audit or of the audits performed during a specified time period. (Findings are retained for 180 days.)
**Synopsis**
```
aws iot list-audit-findings \
[--task-id ] \
[--check-name ] \
[--resource-identifier ] \
[--max-results ] \
[--next-token ] \
[--start-time ] \
[--end-time ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format
```
{
"taskId": "string",
"checkName": "string",
"resourceIdentifier": {
"deviceCertificateId": "string",
"caCertificateId": "string",
"cognitoIdentityPoolId": "string",
"clientId": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string",
"account": "string"
},
"maxResults": "integer",
"nextToken": "string",
"startTime": "timestamp",
"endTime": "timestamp"
}
```
**`cli-input-json` Fields**
| Name | Type | Description |
| --- | --- | --- |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | A filter to limit results to the audit with the specified ID. You must specify either the taskId or the startTime and endTime, but not both. |
| checkName | string | A filter to limit results to the findings for the specified audit check. |
| resourceIdentifier | ResourceIdentifier | Information that identifies the noncompliant resource. |
| deviceCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the certificate attached to the resource. |
| caCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the CA certificate used to authorize the certificate. |
| cognitoIdentityPoolId | string | The ID of the Amazon Cognito identity pool. |
| clientId | string | The client ID. |
| policyVersionIdentifier | PolicyVersionIdentifier | The version of the policy associated with the resource. |
| policyName | string length- max:128 min:1 pattern: [w\$1=,.@-]\$1 | The name of the policy. |
| policyVersionId | string pattern: [0-9]\$1 | The ID of the version of the policy associated with the resource. |
| roleAliasArn | string | The ARN of the role alias that has overly permissive actions. length- max:2048 min:1 |
| account | string length- max:12 min:12 pattern: [0-9]\$1 | The account with which the resource is associated. |
| maxResults | integer range- max:250 min:1 | The maximum number of results to return at one time. The default is 25. |
| nextToken | string | The token for the next set of results. |
| startTime | timestamp | A filter to limit results to those found after the specified time. You must specify either the startTime and endTime or the taskId, but not both. |
| endTime | timestamp | A filter to limit results to those found before the specified time. You must specify either the startTime and endTime or the taskId, but not both. |
Output
```
{
"findings": [
{
"taskId": "string",
"checkName": "string",
"taskStartTime": "timestamp",
"findingTime": "timestamp",
"severity": "string",
"nonCompliantResource": {
"resourceType": "string",
"resourceIdentifier": {
"deviceCertificateId": "string",
"caCertificateId": "string",
"cognitoIdentityPoolId": "string",
"clientId": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"account": "string"
},
"additionalInfo": {
"string": "string"
}
},
"relatedResources": [
{
"resourceType": "string",
"resourceIdentifier": {
"deviceCertificateId": "string",
"caCertificateId": "string",
"cognitoIdentityPoolId": "string",
"clientId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"account": "string"
},
"roleAliasArn": "string",
"additionalInfo": {
"string": "string"
}
}
],
"reasonForNonCompliance": "string",
"reasonForNonComplianceCode": "string"
}
],
"nextToken": "string"
}
```
**CLI output fields**
| Name | Type | Description |
| --- | --- | --- |
| findings | list member: AuditFinding | The findings (results) of the audit. |
| taskId | string length- max:40 min:1 pattern: [a-zA-Z0-9-]\$1 | The ID of the audit that generated this result (finding). |
| checkName | string | The audit check that generated this result. |
| taskStartTime | timestamp | The time the audit started. |
| findingTime | timestamp | The time the result (finding) was discovered. |
| severity | string | The severity of the result (finding). enum: CRITICAL \$1 HIGH \$1 MEDIUM \$1 LOW |
| nonCompliantResource | NonCompliantResource | The resource that was found to be noncompliant with the audit check. |
| resourceType | string | The type of the noncompliant resource. enum: DEVICE\$1CERTIFICATE \$1 CA\$1CERTIFICATE \$1 IOT\$1POLICY \$1 COGNITO\$1IDENTITY\$1POOL \$1 CLIENT\$1ID \$1 ACCOUNT\$1SETTINGS |
| resourceIdentifier | ResourceIdentifier | Information that identifies the noncompliant resource. |
| deviceCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the certificate attached to the resource. |
| caCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the CA certificate used to authorize the certificate. |
| cognitoIdentityPoolId | string | The ID of the Amazon Cognito identity pool. |
| clientId | string | The client ID. |
| policyVersionIdentifier | PolicyVersionIdentifier | The version of the policy associated with the resource. |
| policyName | string length- max:128 min:1 pattern: [w\$1=,.@-]\$1 | The name of the policy. |
| policyVersionId | string pattern: [0-9]\$1 | The ID of the version of the policy associated with the resource. |
| account | string length- max:12 min:12 pattern: [0-9]\$1 | The account with which the resource is associated. |
| additionalInfo | map | Other information about the noncompliant resource. |
| relatedResources | list member: RelatedResource | The list of related resources. |
| resourceType | string | The type of resource. enum: DEVICE\$1CERTIFICATE \$1 CA\$1CERTIFICATE \$1 IOT\$1POLICY \$1 COGNITO\$1IDENTITY\$1POOL \$1 CLIENT\$1ID \$1 ACCOUNT\$1SETTINGS |
| resourceIdentifier | ResourceIdentifier | Information that identifies the resource. |
| deviceCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the certificate attached to the resource. |
| caCertificateId | string length- max:64 min:64 pattern: (0x)?[a-fA-F0-9]\$1 | The ID of the CA certificate used to authorize the certificate. |
| cognitoIdentityPoolId | string | The ID of the Amazon Cognito identity pool. |
| clientId | string | The client ID. |
| policyVersionIdentifier | PolicyVersionIdentifier | The version of the policy associated with the resource. |
| iamRoleArn | string length- max:2048 min:20 | The ARN of the IAM role that has overly permissive actions. |
| policyName | string length- max:128 min:1 pattern: [w\$1=,.@-]\$1 | The name of the policy. |
| policyVersionId | string pattern: [0-9]\$1 | The ID of the version of the policy associated with the resource. |
| roleAliasArn | string length- max:2048 min:1 | The ARN of the role alias that has overly permissive actions. |
| account | string length- max:12 min:12 pattern: [0-9]\$1 | The account with which the resource is associated. |
| additionalInfo | map | Other information about the resource. |
| reasonForNonCompliance | string | The reason the resource was noncompliant. |
| reasonForNonComplianceCode | string | A code that indicates the reason that the resource was noncompliant. |
| nextToken | string | A token that can be used to retrieve the next set of results, or `null` if there are no additional results. |
**Errors**
`InvalidRequestException`
The contents of the request were invalid.
`ThrottlingException`
The rate exceeds the limit.
`InternalFailureException`
An unexpected error has occurred.
# Audit finding suppressions
When you run an audit, it reports findings for all non-compliant resources. This means your audit reports include findings for resources where you're working toward mitigating issues and also for resources that are known to be non-compliant, such as test or broken devices. The audit continues to report findings for resources that remain non-compliant in successive audit runs, which may add unwanted information to your reports. Audit finding suppressions enable you to suppress or filter out findings for a defined period of time until the resource is fixed, or indefinitely for a resource associated with a test or broken device.
**Note**
Mitigation actions won't be available for suppressed audit findings. For more information about mitigation actions, see [Mitigation actions](dd-mitigation-actions.md).
For information about audit finding suppression quotas, see [AWS IoT Device Defender endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_defender.html).
## How audit finding suppressions work
When you create an audit finding suppression for a non-compliant resource, your audit reports and notifications behave differently.
Your audit reports will include a new section that lists all the suppressed findings associated with the report. Suppressed findings won't be considered when we evaluate whether an audit check is compliant or not. A suppressed resource count is also returned for each audit check when you use the [describe-audit-task](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-audit-task.html) command in the command line interface (CLI).
For audit notifications, suppressed findings aren't considered when we evaluate whether an audit check is compliant or not. A suppressed resource count is also included in each audit check notification AWS IoT Device Defender publishes to Amazon CloudWatch and Amazon Simple Notification Service (Amazon SNS).
## How to use audit finding suppressions in the console
**To suppress a finding from an audit report**
The following procedure shows you how to create an audit finding suppression in the AWS IoT console.
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Audit**, **Results**.
1. Select an audit report you'd like to review.
![\[AWS IoT Device Defender audit results table showing compliance status for multiple audits over recent dates, with most audits marked as not compliant.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/audit-results.png)
1. In the **Non-compliant checks** section, under **Check name**, choose the audit check that you're interested in.
![\[Audit report showing one non-compliant check for logging disabled and 13 compliant checks across severity levels critical, high, and medium for an AWS service.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/audit-results-details.png)
1. On the audit check details screen, if there are findings you don't want to see, select the option button next to the finding. Next, choose **Actions**, and then choose the amount of time you'd like your audit finding suppression to persist.
**Note**
In the console, you can select *1 week*, *1 month*, *3 months*, *6 months*, or *Indefinitely* as expiration dates for your audit finding suppression. If you want to set a specific expiration date, you can do so only in the CLI or API. Audit finding suppressions can also be canceled anytime regardless of expiration date.
![\[AWS IoT Device Defender audit findings showing logging disabled and 1 non-compliant account with details and mitigation.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/non-compliant-check.png)
1. Confirm the suppression details, and then choose **Enable suppression**.
![\[Confirm suppression dialog with Logging disabled check name, account settings number, 3 months expiration period, and 2020-10-28 expiration date.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/confirm-suppression.png)
1. After you've created the audit finding suppression, a banner appears confirming your audit finding suppression was created.
![\[AWS IoT Device Defender audit findings page showing one non-compliant account with logging disabled, with mitigation step to enable CloudWatch Logs.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/suppression-created-successfully.png)
**To view your suppressed findings in an audit report**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Audit**, **Results**.
1. Select an audit report you'd like to review.
1. In the **Suppressed findings** section, view which audit findings have been suppressed for your chosen audit report.
![\[AWS IoT Device Defender audit report showing compliance checks with severity levels and findings summary.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/audit-report-findings.png)
**To list your audit finding suppressions**
+ In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Audit**, **Finding suppressions**.
![\[AWS IoT Device Defender Audit finding suppressions table with a single suppression for check "Logging disabled" expiring on October 28, 2020.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/list-suppressions.png)
**To edit your audit finding suppression**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Audit**, **Finding suppressions**.
1. Select the option button next to the audit finding suppression you'd like to edit. Next, choose **Actions**, **Edit**.
1. On the **Edit audit finding suppression** window, you can change the **Suppression duration** or **Description (optional)**.
![\[Edit audit finding suppression dialog with options to suppress "Logging disabled" check for specified resource for 6 months and description field.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/edit-suppression.png)
1. After you've made your changes, choose **Save**. The **Finding suppressions** window opens.
**To delete an audit finding suppression**
1. In the [AWS IoT console](https://console.aws.amazon.com/iot), in the navigation pane, expand **Defend**, and then choose **Audit**, **Finding suppressions**.
1. Select the option button next to the audit finding suppression you'd like to delete, and then choose **Actions**, **Delete**.
1. On the **Delete audit finding suppression** window, enter `delete` in the text box to confirm your deletion, and then choose **Delete**. The **Finding suppressions** window opens.
![\[Dialog box to delete audit finding suppression with input field to enter "delete" and Delete button.\]](http://docs.aws.amazon.com/iot-device-defender/latest/devguide/images/delete-suppression.png)
## How to use audit finding suppressions in the CLI
You can use the following CLI commands to create and manage audit finding suppressions.
+ [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)
The `resource-identifier` you input depends on the `check-name` you're suppressing findings for. The following table details which checks require which `resource-identifier` for creating and editing suppressions.
**Note**
The suppression commands do not indicate turning off an audit. Audits will still run on your AWS IoT devices. Suppressions are only applicable to the audit findings.
| `check-name` | `resource-identifier` |
| --- | --- |
| AUTHENTICATE\$1COGNITO\$1ROLE\$1OVERLY\$1PERMISSIVE\$1CHECK | cognitoIdentityPoolId |
| CA\$1CERT\$1APPROACHING\$1EXPIRATION\$1CHECK | caCertificateId |
| CA\$1CERTIFICATE\$1KEY\$1QUALITY\$1CHECK | caCertificateId |
| CONFLICTING\$1CLIENT\$1IDS\$1CHECK | clientId |
| DEVICE\$1CERT\$1APPROACHING\$1EXPIRATION\$1CHECK | deviceCertificateId |
| DEVICE\$1CERTIFICATE\$1KEY\$1QUALITY\$1CHECK | deviceCertificateId |
| DEVICE\$1CERTIFICATE\$1SHARED\$1CHECK | deviceCertificateId |
| IOT\$1POLICY\$1OVERLY\$1PERMISSIVE\$1CHECK | policyVersionIdentifier |
| IOT\$1ROLE\$1ALIAS\$1ALLOWS\$1ACCESS\$1TO\$1UNUSED\$1SERVICES\$1CHECK | roleAliasArn |
| IOT\$1ROLE\$1ALIAS\$1OVERLY\$1PERMISSIVE\$1CHECK | roleAliasArn |
| LOGGING\$1DISABLED\$1CHECK | account |
| REVOKED\$1CA\$1CERT\$1CHECK | caCertificateId |
| REVOKED\$1DEVICE\$1CERT\$1CHECK | deviceCertificateId |
| UNAUTHENTICATED\$1COGNITO\$1ROLE\$1OVERLY\$1PERMISSIVE\$1CHECK | cognitoIdentityPoolId |
**To create and apply an audit finding suppression**
The following procedure shows you how to create an audit finding suppression in the AWS CLI.
+ Use the `create-audit-suppression` command to create an audit finding suppression. The following example creates an audit finding suppression for AWS account *123456789012* on the basis of the check **Logging disabled**.
```
aws iot create-audit-suppression \
--check-name LOGGING_DISABLED_CHECK \
--resource-identifier account=123456789012 \
--client-request-token 28ac32c3-384c-487a-a368-c7bbd481f554 \
--suppress-indefinitely \
--description "Suppresses logging disabled check because I don't want to enable logging for now."
```
There is no output for this command.
## Audit finding suppressions APIs
The following APIs can be used to create and manage audit finding suppressions.
+ [CreateAuditSuppression](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateAuditSuppression.html)
+ [DescribeAuditSuppression](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeAuditSuppression.html)
+ [UpdateAuditSuppression](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateAuditSuppression.html)
+ [DeleteAuditSuppression](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteAuditSuppression.html)
+ [ListAuditSuppressions](https://docs.aws.amazon.com/iot/latest/apireference/API_ListAuditSuppressions.html)
To filter *for* specific audit findings, you can use the [ListAuditFindings](https://docs.aws.amazon.com/iot/latest/apireference/API_ListAuditFindings.html) API.