# Runtime coverage and troubleshooting for Amazon EC2 instance
Coverage and troubleshooting for Amazon EC2 resources

For an Amazon EC2 resource, the runtime coverage is evaluated at the instance level. Your Amazon EC2 instances can run multiple types of applications and workloads amongst others in your Amazon environment. This feature also supports Amazon ECS managed Amazon EC2 instances and if you have Amazon ECS clusters running on an Amazon EC2 instance, the coverage issues at the instance level will show up under Amazon EC2 runtime coverage. 

**Topics**
+ [

## Reviewing coverage statistics
](#review-coverage-statistics-ec2-runtime-monitoring)
+ [

## Coverage status change with EventBridge notifications
](#ec2-runtime-monitoring-coverage-status-change)
+ [

## Troubleshooting Amazon EC2 runtime coverage issues
](#ec2-runtime-monitoring-coverage-issues-troubleshoot)

## Reviewing coverage statistics


The coverage statistics for the Amazon EC2 instances associated with your own accounts or your member accounts is the percentage of the healthy EC2 instances over all EC2 instances in the selected Amazon Web Services Region. The following equation represents this as:

*(Healthy instances/All instances)\$1100*

If you have also deployed the GuardDuty security agent for your Amazon ECS clusters, then any instance level coverage issue associated with Amazon ECS clusters running on an Amazon EC2 instance will appear as an Amazon EC2 instance runtime coverage issue. 

Choose one of the access methods to review the coverage statistics for your accounts.

------
#### [ Console ]
+ Sign in to the Amazon Web Services Management Console and open the GuardDuty console at [https://console.amazonaws.cn/guardduty/](https://console.amazonaws.cn/guardduty/).
+ In the navigation pane, choose **Runtime Monitoring**.
+ Choose the **Runtime coverage** tab.
+ Under the **EC2 instance runtime coverage** tab, you can view the coverage statistics aggregated by the coverage status of each Amazon EC2 instance that is available in the **Instances list** table. 
  + You can filter the **Instance list** table by the following columns:
    + **Account ID**
    + **Agent management type**
    + **Agent version**
    + **Coverage status**
    + **Instance ID**
    + **Cluster ARN**
+ If any of your EC2 instances have the **Coverage status** as **Unhealthy**, the **Issue** column includes additional information about the reason for the **Unhealthy** status.

------
#### [ API/CLI ]
+ Run the [ListCoverage](https://docs.amazonaws.cn/guardduty/latest/APIReference/API_ListCoverage.html) API with your own valid detector ID, current Region, and service endpoint. You can filter and sort the instance list using this API.
  + You can change the example `filter-criteria` with one of the following options for `CriterionKey`:
    + `ACCOUNT_ID`
    + `RESOURCE_TYPE`
    + `COVERAGE_STATUS`
    + `AGENT_VERSION`
    + `MANAGEMENT_TYPE`
    + `INSTANCE_ID`
    + `CLUSTER_ARN`
  + When the `filter-criteria` includes `RESOURCE_TYPE` as **EC2**, Runtime Monitoring doesn't support the use of **ISSUE** as the `AttributeName`. If you use it, the API response will result in `InvalidInputException`.

    You can change the example `AttributeName` in `sort-criteria` with the following options:
    + `ACCOUNT_ID`
    + `COVERAGE_STATUS`
    + `INSTANCE_ID`
    + `UPDATED_AT`
  + You can change the *max-results* (up to 50).
  + To find the `detectorId` for your account and current Region, see the **Settings** page in the [https://console.amazonaws.cn/guardduty/](https://console.amazonaws.cn/guardduty/) console, or run the [https://docs.amazonaws.cn/guardduty/latest/APIReference/API_ListDetectors.html](https://docs.amazonaws.cn/guardduty/latest/APIReference/API_ListDetectors.html) API.

  ```
  aws guardduty --region us-east-1 list-coverage --detector-id 12abc34d567e8fa901bc2d34e56789f0 --sort-criteria '{"AttributeName": "EKS_CLUSTER_NAME", "OrderBy": "DESC"}' --filter-criteria '{"FilterCriterion":[{"CriterionKey":"ACCOUNT_ID", "FilterCondition":{"EqualsValue":"111122223333"}}] }'  --max-results 5
  ```
+ Run the [GetCoverageStatistics](https://docs.amazonaws.cn/guardduty/latest/APIReference/API_GetCoverageStatistics.html) API to retrieve coverage aggregated statistics based on the `statisticsType`.
  + You can change the example `statisticsType` to one of the following options:
    + `COUNT_BY_COVERAGE_STATUS` – Represents coverage statistics for EKS clusters aggregated by coverage status.
    + `COUNT_BY_RESOURCE_TYPE` – Coverage statistics aggregated based on the type of Amazon resource in the list.
    + You can change the example `filter-criteria` in the command. You can use the following options for `CriterionKey`:
      + `ACCOUNT_ID`
      + `RESOURCE_TYPE`
      + `COVERAGE_STATUS`
      + `AGENT_VERSION`
      + `MANAGEMENT_TYPE`
      + `INSTANCE_ID`
      + `CLUSTER_ARN`
  + To find the `detectorId` for your account and current Region, see the **Settings** page in the [https://console.amazonaws.cn/guardduty/](https://console.amazonaws.cn/guardduty/) console, or run the [https://docs.amazonaws.cn/guardduty/latest/APIReference/API_ListDetectors.html](https://docs.amazonaws.cn/guardduty/latest/APIReference/API_ListDetectors.html) API.

  ```
  aws guardduty --region us-east-1 get-coverage-statistics --detector-id 12abc34d567e8fa901bc2d34e56789f0 --statistics-type COUNT_BY_COVERAGE_STATUS --filter-criteria '{"FilterCriterion":[{"CriterionKey":"ACCOUNT_ID", "FilterCondition":{"EqualsValue":"123456789012"}}] }'
  ```

------

If the coverage status of your EC2 instance is **Unhealthy**, see [Troubleshooting Amazon EC2 runtime coverage issues](#ec2-runtime-monitoring-coverage-issues-troubleshoot).

## Coverage status change with EventBridge notifications


The coverage status of your Amazon EC2 instance might appear as **Unhealthy**. To know when the coverage status changes, we recommend you to monitor the coverage status periodically, and troubleshoot if the status becomes **Unhealthy**. Alternatively, you can create an Amazon EventBridge rule to receive a notification when the coverage status changes from either **Unhealthy** to **Healthy** or otherwise. By default, GuardDuty publishes this in the [EventBridge bus](https://docs.amazonaws.cn/eventbridge/latest/userguide/eb-event-bus.html) for your account.

### Sample notification schema


In an EventBridge rule, you can use the pre-defined sample events and event patterns to receive coverage status notification. For more information about creating an EventBridge rule, see [Create rule](https://docs.amazonaws.cn/eventbridge/latest/userguide/eb-get-started.html#eb-gs-create-rule) in the *Amazon EventBridge User Guide*. 

Additionally, you can create a custom event pattern by using the following example notification schema. Make sure to replace the values for your account. To get notified when the coverage status of your Amazon EC2 instance changes from `Healthy` to `Unhealthy`, the `detail-type` should be *GuardDuty Runtime Protection Unhealthy*. To get notified when the coverage status changes from `Unhealthy` to `Healthy`, replace the value of `detail-type` with *GuardDuty Runtime Protection Healthy*.

```
{
  "version": "0",
  "id": "event ID",
  "detail-type": "GuardDuty Runtime Protection Unhealthy",
  "source": "aws.guardduty",
  "account": "Amazon Web Services account ID",
  "time": "event timestamp (string)",
  "region": "Amazon Web Services Region",
  "resources": [
       ],
  "detail": {
    "schemaVersion": "1.0",
    "resourceAccountId": "string",
    "currentStatus": "string",
    "previousStatus": "string",
    "resourceDetails": {
        "resourceType": "EC2",
        "ec2InstanceDetails": {
          "instanceId":"",
          "instanceType":"",
          "clusterArn": "",
          "agentDetails": {
            "version":""
          },
          "managementType":""
        }
    },
    "issue": "string",
    "lastUpdatedAt": "timestamp"
  }
}
```

## Troubleshooting Amazon EC2 runtime coverage issues


If the coverage status of your Amazon EC2 instance is **Unhealthy**, you can view the reason under the **Issue** column.

If your EC2 instance is associated with an EKS cluster and the security agent for EKS was installed either manually or through automated agent configuration, then to troubleshoot the coverage issue, see [Runtime coverage and troubleshooting for Amazon EKS clusters](eks-runtime-monitoring-coverage.md).

The following table lists the issue types and the corresponding troubleshooting steps.

[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/guardduty/latest/ug/gdu-assess-coverage-ec2.html)