Enabling and configuring the integration How AWS IoT Device Defender sends findings to Security Hub Typical finding from AWS IoT Device Defender Stopping AWS IoT Device Defender from sending findings to Security Hub

Integration with AWS Security Hub

AWS Security Hub provides you with a comprehensive view of your security state in AWS and helps you check your environment against security industry standards and best practices. Security Hub collects security data from across AWS accounts, services, and supported third-party products. You can use Security Hub to analyze your security trends and identify the highest priority security issues.

With the AWS IoT Device Defender integration with Security Hub, you can send findings from AWS IoT Device Defender to Security Hub. Security Hub includes those findings in its analysis of your security posture.

Enabling and configuring the integration

Before you integrate AWS IoT Device Defender with Security Hub, you must first enable Security Hub. For information about how to enable Security Hub, see Setting up Security Hub in the AWS Security Hub User Guide.

After you enable both AWS IoT Device Defender and Security Hub, open the Integrations page in the Security Hub console, and then choose Accept findings for Audit, Detect, or both. AWS IoT Device Defender begins sending findings to Security Hub.

How AWS IoT Device Defender sends findings to Security Hub

In Security Hub, security issues are tracked as findings. Some findings come from issues that are detected by other AWS services or by third-party products.

Security Hub provides tools to manage findings from across all of these sources. You can view and filter lists of findings and view details for a finding. For more information, see Viewing findings in the AWS Security Hub User Guide. You can also track the status of an investigation into a finding. For more information, see Taking action on findings in the AWS Security Hub User Guide.

All findings in Security Hub use a standard JSON format called the AWS Security Finding Format (ASFF). The ASFF includes details about the source of the issue, the affected resources, and the current status of the finding. For more information about ASFF, see AWS Security Finding Format (ASFF) in the AWS Security Hub User Guide.

AWS IoT Device Defender is one of the AWS services that sends findings to Security Hub.

Types of findings that AWS IoT Device Defender sends

After you enable the Security Hub integration, AWS IoT Device Defender Audit sends the findings it generates (called check summaries) to Security Hub. Check summaries are general information for a specific audit check type and a specific audit task. For more information, see Audit checks.

AWS IoT Device Defender Audit sends finding updates to Security Hub for both Audit Check Summaries and Audit Findings in each Audit task. If all resources found in Audit Checks are compliant, or an Audit Task is canceled, Audit updates the Check Summaries in Security Hub to an ARCHIVED record state. If a resource was reported as non-compliant for an Audit Check, but was reported as compliant in the last Audit task, Audit changes it to compliant and also updates the finding in Security Hub to an ARCHIVED record state.

AWS IoT Device Defender Detect sends violation findings to Security Hub. These violation findings include machine learning (ML), statistical, and static behaviors.

To send the findings to Security Hub, AWS IoT Device Defender uses the AWS Security Finding Format (ASFF). In ASFF, the Types field provides the finding type. Findings from AWS IoT Device Defender can have the following values for Types.

Unusual behaviors: The finding type for conflicting MQTT client IDs and device certificate shared checks, and the finding type for Detect.
Software and Configuration Check/Vulnerabilities: The finding type for all other Audit checks.

Latency for sending findings

When AWS IoT Device Defender Audit creates a new finding, it's immediately sent to Security Hub after the audit task completes. The latency depends on the volume of the findings generated in the audit task. Security Hub typically receives the findings within one hour.

AWS IoT Device Defender Detect sends findings for violations in near real time. After a violation goes into or out of alarm (meaning the alarm is created or deleted), the corresponding Security Hub finding is immediately created or archived.

Retrying when Security Hub isn't available

If Security Hub isn't available, AWS IoT Device Defender Audit and AWS IoT Device Defender Detect retry sending the findings until they're received.

Updating existing findings in Security Hub

After an AWS IoT Device Defender Audit finding is sent to Security Hub, you can identify it by checked resource identifier and audit check type. If a new audit finding is generated with a subsequent audit task for the same resource and audit check, AWS IoT Device Defender Audit sends updates to reflect additional observations of the finding activity to Security Hub. If no additional audit finding is generated with a subsequent audit task for the same resource and audit check, the resource changes to compliant with the audit check. AWS IoT Device Defender Audit then archives the findings in Security Hub.

AWS IoT Device Defender Audit also updates check summaries in Security Hub. If there are non-compliant resources found in an audit check or the check fails, the status of the Security Hub finding becomes active. Otherwise, AWS IoT Device Defender Audit archives the finding in Security Hub.

AWS IoT Device Defender Detect creates a Security Hub finding when there's a violation (for example, in-alarm). That finding is updated only if one of the following criteria is met:

The finding is expiring soon in Security Hub so AWS IoT Device Defender sends an update to keep the finding current. Findings are deleted 90 days after the most recent update or 90 days after the creation date if no update occurs. For more information, see Security Hub quotas in the AWS Security Hub User Guide.
The corresponding violation goes out of alarm, so AWS IoT Device Defender updates its finding status to ARCHIVED.

Typical finding from AWS IoT Device Defender

AWS IoT Device Defender uses the AWS Security Finding Format (ASFF) to send findings to Security Hub.

The following example shows a typical finding from Security Hub for an audit finding. The ReportType in ProductFields is AuditFinding.



  {
  "SchemaVersion": "2018-10-08",
  "Id": "336757784525/IOT_POLICY/policyexample/1/IOT_POLICY_OVERLY_PERMISSIVE_CHECK/ALLOWS_BROAD_ACCESS_TO_IOT_DATA_PLANE_ACTIONS",
  "ProductArn": "arn:aws:securityhub:us-west-2::product/aws/iot-device-defender-audit",
  "ProductName": "IoT Device Defender - Audit",
  "CompanyName": "AWS",
  "Region": "us-west-2",
  "GeneratorId": "1928b87ab338ee2f541f6fab8c41c4f5",
  "AwsAccountId": "123456789012",
  "Types": [
    "Software and Configuration Check/Vulnerabilities"
  ],
  "CreatedAt": "2022-11-06T22:11:40.941Z",
  "UpdatedAt": "2022-11-06T22:11:40.941Z",
  "Severity": {
    "Label": "CRITICAL",
    "Normalized": 90
  },
  "Title": "IOT_POLICY_OVERLY_PERMISSIVE_CHECK: ALLOWS_BROAD_ACCESS_TO_IOT_DATA_PLANE_ACTIONS",
  "Description": "IOT_POLICY policyexample:1 is reported as non-compliant for IOT_POLICY_OVERLY_PERMISSIVE_CHECK by Audit task 9f71b6e90cfb57d4ac671be3a4898e6a. The non-compliant reason is Policy allows broad access to IoT data plane actions: [iot:Connect].",
  "SourceUrl": "https://us-west-2.console.aws.amazon.com/iot/home?region=us-west-2#/policy/policyexample",
  "ProductFields": {
    "CheckName": "IOT_POLICY_OVERLY_PERMISSIVE_CHECK",
    "TaskId": "9f71b6e90cfb57d4ac671be3a4898e6a",
    "TaskType": "ON_DEMAND_AUDIT_TASK",
    "PolicyName": "policyexample",
    "IsSuppressed": "false",
    "ReasonForNonComplianceCode": "ALLOWS_BROAD_ACCESS_TO_IOT_DATA_PLANE_ACTIONS",
    "ResourceType": "IOT_POLICY",
    "FindingId": "1928b87ab338ee2f541f6fab8c41c4f5",
    "PolicyVersionId": "1",
    "ReportType": "AuditFinding",
    "TaskStartTime": "1667772700554",
    "aws/securityhub/FindingId": "arn:aws:securityhub:us-west-2::product/aws/iot-device-defender-audit/336757784525/IOT_POLICY/policyexample/1/IOT_POLICY_OVERLY_PERMISSIVE_CHECK/ALLOWS_BROAD_ACCESS_TO_IOT_DATA_PLANE_ACTIONS",
    "aws/securityhub/ProductName": "IoT Device Defender - Audit",
    "aws/securityhub/CompanyName": "AWS"
  },
  "Resources": [
    {
      "Type": "AwsIotPolicy",
      "Id": "policyexample",
      "Partition": "aws",
      "Region": "us-west-2",
      "Details": {
        "Other": {
          "PolicyVersionId": "1"
        }
      }
    }
  ],
  "WorkflowState": "NEW",
  "Workflow": {
    "Status": "NEW"
  },
  "RecordState": "ACTIVE",
  "FindingProviderFields": {
    "Severity": {
      "Label": "CRITICAL"
    },
    "Types": [
      "Software and Configuration Check/Vulnerabilities"
    ]
  }
}

The following example shows a finding from Security Hub for an audit check summary. The ReportType in ProductFields is CheckSummary.



  {
  "SchemaVersion": "2018-10-08",
  "Id": "615243839755/SCHEDULED_AUDIT_TASK/daily_audit_schedule_checks/DEVICE_CERTIFICATE_KEY_QUALITY_CHECK",
  "ProductArn": "arn:aws:securityhub:us-east-1::product/aws/iot-device-defender-audit",
  "ProductName": "IoT Device Defender - Audit",
  "CompanyName": "AWS",
  "Region": "us-east-1",
  "GeneratorId": "f3021945485adf92487c273558fcaa51",
  "AwsAccountId": "123456789012",
  "Types": [
    "Software and Configuration Check/Vulnerabilities/CVE"
  ],
  "CreatedAt": "2022-10-18T14:20:13.933Z",
  "UpdatedAt": "2022-10-18T14:20:13.933Z",
  "Severity": {
    "Label": "CRITICAL",
    "Normalized": 90
  },
  "Title": "DEVICE_CERTIFICATE_KEY_QUALITY_CHECK Summary: Completed with 2 non-compliant resources",
  "Description": "Task f3021945485adf92487c273558fcaa51 of weekly scheduled Audit daily_audit_schedule_checks completes. 2 non-cimpliant resources are found for DEVICE_CERTIFICATE_KEY_QUALITY_CHECK out of 1000 resources in the account. The percentage of non-compliant resources is 0.2%.",
  "SourceUrl": "https://us-east-1.console.aws.amazon.com/iot/home?region=us-east-1#/dd/audit/results/f3021945485adf92487c273558fcaa51/DEVICE_CERTIFICATE_KEY_QUALITY_CHECK",
  "ProductFields": {
    "TaskId": "f3021945485adf92487c273558fcaa51",
    "TaskType": "SCHEDULED_AUDIT_TASK",
    "ScheduledAuditName": "daily_audit_schedule_checks",
    "CheckName": "DEVICE_CERTIFICATE_KEY_QUALITY_CHECK",
    "ReportType": "CheckSummary",
    "CheckRunStatus": "COMPLETED_NON_COMPLIANT",
    "NonComopliantResourcesCount": "2",
    "SuppressedNonCompliantResourcesCount": "1",
    "TotalResourcesCount": "1000",
    "aws/securityhub/FindingId": "arn:aws:securityhub:us-east-1::product/aws/iot-device-defender-audit/615243839755/SCHEDULED/daily_audit_schedule_checks/DEVICE_CERTIFICATE_KEY_QUALITY_CHECK",
    "aws/securityhub/ProductName": "IoT Device Defender - Audit",
    "aws/securityhub/CompanyName": "AWS"
  },
  "Resources": [
    {
      "Type": "AwsIotAuditTask",
      "Id": "f3021945485adf92487c273558fcaa51",
      "Region": "us-east-1"
    }
  ],
  "WorkflowState": "NEW",
  "Workflow": {
    "Status": "NEW"
  },
  "RecordState": "ACTIVE",
  "FindingProviderFields": {
    "Severity": {
      "Label": "CRITICAL"
    },
    "Types": [
      "Software and Configuration Check/Vulnerabilities/CVE"
    ]
  }
}

The following example shows a typical finding from Security Hub for an AWS IoT Device Defender Detect violation.



  {
  "SchemaVersion": "2018-10-08",
  "Id": "e92a782593c6f5b1fc7cb6a443dc1a12",
  "ProductArn": "arn:aws:securityhub:us-east-1::product/aws/iot-device-defender-detect",
  "ProductName": "IoT Device Defender - Detect",
  "CompanyName": "AWS",
  "Region": "us-east-1",
  "GeneratorId": "arn:aws:iot:us-east-1:123456789012:securityprofile/MySecurityProfile",
  "AwsAccountId": "123456789012",
  "Types": [
    "Unusual Behaviors"
  ],
  "CreatedAt": "2022-11-09T22:45:00Z",
  "UpdatedAt": "2022-11-09T22:45:00Z",
  "Severity": {
    "Label": "MEDIUM",
    "Normalized": 40
  },
  "Title": "Registered thing MyThing is in alarm for STATIC behavior MyBehavior.",
  "Description": "Registered thing MyThing violates STATIC behavior MyBehavior of security profile MySecurityProfile. Violation was triggered because the device did not conform to aws:num-disconnects less-than 1.",
  "SourceUrl": "https://us-east-1.console.aws.amazon.com/iot/home?region=us-east-1#/dd/securityProfile/MySecurityProfile?tab=violations",
  "ProductFields": {
    "ComparisonOperator": "less-than",
    "BehaviorName": "MyBehavior",
    "ViolationId": "e92a782593c6f5b1fc7cb6a443dc1a12",
    "ViolationStartTime": "1668033900000",
    "SuppressAlerts": "false",
    "ConsecutiveDatapointsToAlarm": "1",
    "ConsecutiveDatapointsToClear": "1",
    "DurationSeconds": "300",
    "Count": "1",
    "MetricName": "aws:num-disconnects",
    "BehaviorCriteriaType": "STATIC",
    "ThingName": "MyThing",
    "SecurityProfileName": "MySecurityProfile",
    "aws/securityhub/FindingId": "arn:aws:securityhub:us-east-1::product/aws/iot-device-defender-detect/e92a782593c6f5b1fc7cb6a443dc1a12",
    "aws/securityhub/ProductName": "IoT Device Defender - Detect",
    "aws/securityhub/CompanyName": "AWS"
  },
  "Resources": [
    {
      "Type": "AwsIotRegisteredThing",
      "Id": "MyThing",
      "Region": "us-east-1",
      "Details": {
        "Other": {
          "SourceUrl": "https://us-east-1.console.aws.amazon.com/iot/home?region=us-east-1#/thing/MyThing?tab=violations",
          "IsRegisteredThing": "true",
          "ThingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyThing"
        }
      }
    }
  ],
  "WorkflowState": "NEW",
  "Workflow": {
    "Status": "NEW"
  },
  "RecordState": "ACTIVE",
  "FindingProviderFields": {
    "Severity": {
      "Label": "MEDIUM"
    },
    "Types": [
      "Unusual Behaviors"
    ]
  }
}

Stopping AWS IoT Device Defender from sending findings to Security Hub

To stop sending findings to Security Hub, you can use either the Security Hub console or the API.

For more information, see Disabling and enabling the flow of findings from an integration (console) or Disabling the flow of findings from an integration (Security Hub API, AWS CLI) in the AWS Security Hub User Guide.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Using AWS IoT Device Defender with other AWS services

Cross-service confused deputy prevention