Troubleshooting Bottlerocket ECS-EC2 runtime coverage issues

Runtime coverage and troubleshooting for ECS-EC2 Bottlerocket

For Bottlerocket Amazon EC2 instances in Amazon ECS clusters, GuardDuty evaluates runtime coverage at the instance level. The GuardDuty security agent runs as a host container on Bottlerocket, rather than as an installed RPM or Debian package.

Bottlerocket Amazon EC2 instances appear under the EC2 instance runtime coverage tab. To review coverage statistics for your Bottlerocket instances, open the GuardDuty console, choose Runtime Monitoring in the navigation pane, and then choose the Runtime coverage tab. Under EC2 instance runtime coverage, you can view the coverage status of each instance and filter by account ID, agent version, or coverage status. For more information, see Reviewing coverage statistics.

Troubleshooting Bottlerocket ECS-EC2 runtime coverage issues

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

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

Issue type	Issue message	Troubleshooting steps
No Agent Reporting	Waiting for SSM notification	Receiving the SSM notification might take a few minutes. Make sure that your Bottlerocket instance is SSM managed. The SSM agent runs in the Bottlerocket control container by default. Verify that the instance profile includes the `AmazonSSMManagedInstanceCore` and `AmazonEC2ContainerRegistryReadOnly` managed policies.
No Agent Reporting	Not applicable	Verify that the agent host container is enabled and running: Connect to your instance using SSM Session Manager. Enter the admin container: `enter-admin-container`. Verify settings: `apiclient get settings.host-containers.amazon-guardduty-agent`. Confirm that `enabled` is `true` and `superpowered` is `true`. Check if the agent process is running: `sheltie ps aux \| grep guardduty`. Check agent logs using one of the following: `sheltie journalctl -u host-containers@amazon-guardduty-agent` From a sheltie session (`sudo sheltie`): `ls /var/log/amzn-guardduty-agent/`.
No Agent Reporting	Not applicable	Validate that the instance has network connectivity to the Amazon ECR endpoint and the GuardDuty VPC endpoint. If your instance runs in a private subnet, make sure you have configured VPC endpoints for both Amazon ECR and GuardDuty.
No Agent Reporting	Not applicable	If your organization has a service control policy (SCP), confirm that the permissions boundary allows the `guardduty:SendSecurityTelemetry` permission.
SSM Association Creation Failed	GuardDuty SSM association already exists in your account.	Delete the existing association manually. For more information, see Deleting associations in the AWS Systems Manager User Guide. After you delete the association, disable and then re-enable the GuardDuty automated agent configuration for Amazon EC2.
SSM Association Creation Failed	Your account has too many SSM associations.	Choose one of the following two options: Delete any unused SSM associations. For more information, see Deleting associations in the AWS Systems Manager User Guide. Check if your account is eligible for a quota increase. For more information, see Systems Manager Service quotas in the AWS General Reference.
SSM Association Update Failed	GuardDuty SSM association does not exist in your account.	GuardDuty SSM association is not present in your account. Disable and then re-enable Runtime Monitoring.
SSM Association Deletion Failed	GuardDuty SSM association does not exist in your account.	The SSM association is not present in your account. If the SSM association was deleted intentionally, then no action is needed.
SSM Instance Association Execution Failed	Architectural requirements or other prerequisites are not met.	For information about verified requirements, see Prerequisites for ECS-EC2 Bottlerocket support. If you still experience this issue, check the SSM State Manager execution history: Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/. In the navigation pane, under Node management, select State Manager. Filter by Document Name property and enter AmazonGuardDuty-ConfigureRuntimeMonitoringSsmPlugin. Select the corresponding association ID and view its Execution history. Using the execution history, view the failures, identify the potential root cause, and try to resolve it.
Agent disconnected	Not applicable	Check agent logs from the admin container: `enter-admin-container sheltie journalctl -u host-containers@amazon-guardduty-agent` Verify the agent container image was pulled successfully by checking that the `source` field in host container settings points to a valid Amazon ECR URI. Make sure the instance profile has Amazon ECR pull permissions. For more information, see Make EC2 instances SSM managed and configure instance permissions.
Agent Not Provisioned	Instances with exclusion tags are excluded from Runtime Monitoring.	GuardDuty doesn't receive runtime events from Amazon EC2 instances that are launched with the exclusion tag `GuardDutyManaged`:`false`. To receive runtime events from this instance, remove the exclusion tag.
Agent Not Provisioned	Kernel version is lower than the supported version.	Update to the latest Bottlerocket ECS-2 or ECS-3 optimized AMI `v1.62.1` or later for automated agent configuration.
ECR Image Pull Failed	The agent container image could not be pulled from Amazon ECR.	Verify the instance profile includes `AmazonEC2ContainerRegistryReadOnly` managed policy or the required individual Amazon ECR permissions. Verify network connectivity to the Amazon ECR endpoint in your Region. If using a private subnet, make sure VPC endpoints are configured. For more information, see Network connectivity requirements.

Document Conventions

Coverage and troubleshooting for Amazon EC2 resources

Coverage and troubleshooting for Amazon ECS clusters