# 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.