# Runtime Monitoring for EC2 workloads on Amazon ECS
<a name="ecs-guard-duty-configure-manual"></a>

Use this option when you use EC2 instances for your capacity, or when you need granular control of Runtime Monitoring at the cluster-level on Fargate.

You provision the clusters for Runtime Monitoring by adding a pre-defined tag. 

For EC2 container instances, you download, install, and manage the GuardDuty security agent.

For Fargate, GuardDuty manages the security agent on your behalf.

# Turning on Runtime Monitoring for Amazon ECS
<a name="ecs-guard-duty-configure-manual-guard-duty"></a>

You can turn on Runtime Monitoring for clusters with EC2 instances, or when you need granular control of Runtime Monitoring at the cluster-level on Fargate.

The following are prerequisites for using Runtime Monitoring:
+ The Fargate platform version must be `1.4.0` or later for Linux. 
+ IAM roles and permissions for Amazon ECS:
  + Fargate tasks must use a task execution role. This role grants the tasks permission to retrieve, update, and manage the GuardDuty security agent on your behalf. For more information see [Amazon ECS task execution IAM role](task_execution_IAM_role.md).
  + You control Runtime Monitoring for a cluster with a pre-defined tag. If your access policies restrict access based on tags, you must grant explicit permissions to your IAM users to tag clusters. For more information, see [IAM tutorial: Define permissions to access AWS resources based on tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the *IAM User Guide*.
+ Connecting to the Amazon ECR repository:

  The GuardDuty security agent is stored in an Amazon ECR repository. Each standalone and service task must have access to the repository. You can use one of the following options:
  + For tasks in public subnets, you can either use a public IP address for the task, or create a VPC endpoint for Amazon ECR in the subnet where the task runs. For more information, see [Amazon ECR interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/vpc-endpoints.html) in the *Amazon Elastic Container Registry User Guide*.
  + For tasks in private subnets, you can use a Network Address Translation (NAT) gateway, or create a VPC endpoint for Amazon ECR in the subnet where the task runs.

    For more information, see [Private subnet and NAT gateway](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/networking-outbound.html#networking-private-subnet).
+ You must have the `AWSServiceRoleForAmazonGuardDuty` role for GuardDuty. For more information, see [Service-linked role permissions for GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/slr-permissions.html) in the *Amazon GuardDuty User Guide*.
+ Any files that you want to protect with Runtime Monitoring must be accessible by the root user. If you manually changed the permissions of a file, you must set it to `755`.

The following are prerequisites for using Runtime Monitoring on EC2 container instances:
+ You must use version `20230929` or later of the Amazon ECS-AMI.
+ You must run Amazon ECS agent to version `1.77` or later on the container instances.
+ You must use kernel version `5.10` or later.
+ For information about the supported Linux operating systems and architectures, see [Which operating models and workloads does GuardDuty Runtime Monitoring support](https://aws.amazon.com//guardduty/faqs/?nc1=h_ls#product-faqs#guardduty-faqs#guardduty-ecs-runtime-monitoring).
+ You can use Systems Manager to manage your container instances. For more information, see [Setting up Systems Manager for EC2 instances](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-ec2.html) in the *AWS Systems Manager Session Manager User Guide*.

You turn on Runtime Monitoring in GuardDuty. For information about how to enable the feature, see [Enabling Runtime Monitoring](https://docs.aws.amazon.com/guardduty/latest/ug/runtime-monitoring-configuration.html) in the *Amazon GuardDuty User Guide*. 

# Adding Runtime Monitoring an Amazon ECS cluster
<a name="ecs-guard-duty-configure-manual-customize"></a>

Configure Runtime Monitoring for the cluster, and then install the GuardDuty security agent on your EC2 container instances.

## Prerequisites
<a name="ecs-guard-duty-configure-manual-customize-prereq"></a>

1. Turn on Runtime Monitoring. For more information, see [Turning on Runtime Monitoring for Amazon ECS](ecs-guard-duty-configure-manual-guard-duty.md).

1. You control Runtime Monitoring for a cluster with a pre-defined tag. If your access policies restrict access based on tags, you must grant explicit permissions to your IAM users to tag clusters. For more information, see [IAM tutorial: Define permissions to access AWS resources based on tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the *IAM User Guide*.

## Procedure
<a name="ecs-guard-duty-configure-manual-customize-procedure"></a>

Perform the following operations to add Runtime Monitoring to a cluster.

1. Create a VPC endpoint for GuardDuty for each cluster VPC. For more information, see [Creating Amazon VPC endpoint manually ](https://docs.aws.amazon.com/guardduty/latest/ug/managing-gdu-agent-ec2-manually.html#creating-vpc-endpoint-ec2-agent-manually) in the *GuardDuty User Guide*.

1. Configure the EC2 container instances.

   1. Update the Amazon ECS agent to version `1.77` or later on the EC2 container instances in the cluster. For more information see [Updating the Amazon ECS container agent](ecs-agent-update.md).

   1. Install the GuardDuty security agent on the EC2 container instances in the cluster. For more information, see [Managing the security agent on an Amazon EC2 instance manually](https://docs.aws.amazon.com/guardduty/latest/ug/managing-gdu-agent-ec2-manually.html) in the *GuardDuty User Guide*.

      All new and existing tasks, and deployments are immediately protected because the GuardDuty security agent runs as a process on the EC2 container instance.

1. Use the Amazon ECS console or AWS CLI to set the `GuardDutyManaged` tag key on the cluster to `true`. For more information, see [Updating a cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-cluster-v2.html) or [Working with tags using the CLI or API](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-using-tags.html#tag-resources-api-sdk). Use the following values for the tag.
**Note**  
The Key and Value are case sensitive and must exactly match the strings.

   Key = `GuardDutyManaged`, Value = `true`

# Adding Runtime Monitoring to existing Amazon ECS tasks
<a name="ecs-guard-duty-configure-manual-existing-tasks"></a>

When you turn on Runtime Monitoring, all new standalone tasks, and new service deployments in the cluster are protected automatically. In order to preserve the immutability constraint, existing tasks are not affected.

## Prerequisites
<a name="ecs-guard-duty-configure-manual-existing-tasks-prerequisites"></a>
+ Turn on Runtime Monitoring. For more information, see [Turning on Runtime Monitoring for Amazon ECS](ecs-guard-duty-configure-manual-guard-duty.md).

## Procedure
<a name="ecs-guard-duty-configure-manual-existing-tasks-procedure"></a>
+  To immediately protect a task, you need to perform one of the following actions:
  + For standalone tasks, stop the tasks, and then start them. For more information, see [Stopping an Amazon ECS task](standalone-task-stop.md) and [Running an application as an Amazon ECS task](standalone-task-create.md).
  + For tasks that are part of a service, update the service with the "force new deployment" option. For more information, see [Updating an Amazon ECS service](update-service-console-v2.md).

# Removing Runtime Monitoring from an Amazon ECS cluster
<a name="ecs-guard-duty-remove-manual"></a>

You can remove Runtime Monitoring from a cluster. This causes GuardDuty to stop monitoring all resources in the cluster.

**To remove Runtime Monitoring from a cluster**

1. Use the Amazon ECS console or AWS CLI to set the `GuardDutyManaged` tag key on the cluster to `false`. For more information, see [Updating a cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-cluster-v2.html) or [Working with tags using the CLI or API](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-using-tags.html#tag-resources-api-sdk).
**Note**  
The Key and Value are case sensitive and must exactly match the strings.

   Key = `GuardDutyManaged`, Value = `false`

1. Uninstall the GuardDuty security agent on you EC2 container instances in the cluster.

   For more information, see [Uninstalling the security agent manually](https://docs.aws.amazon.com/guardduty/latest/ug/managing-gdu-agent-ec2-manually.html#gdu-update-security-agent-ec2) in the *GuardDuty User Guide*.

1. Delete the GuardDuty VPC endpoint for each cluster VPC. For more information about how to delete VPC endpoints, see [Delete an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html) in the *AWS PrivateLink User Guide*.

# Updating the GuardDuty security agent on your Amazon ECS container instances
<a name="ecs-guard-duty-manage-update-agent"></a>

For information about how to update the GuardDuty security agent on your EC2 container instances, see [Updating GuardDuty security agent](https://docs.aws.amazon.com/guardduty/latest/ug/managing-gdu-agent-ec2-manually.html#gdu-update-security-agent-ec2) in the *Amazon GuardDuty User Guide*.

# Removing Runtime Monitoring for Amazon ECS from an account
<a name="ecs-guard-duty-manage-remove-protection-manual"></a>

When you no longer want to use Runtime Monitoring, disable the feature in GuardDuty. For information about how to disable the feature, see [Enabling Runtime Monitoring](https://docs.aws.amazon.com/guardduty/latest/ug/runtime-monitoring-configuration.html) in the *Amazon GuardDuty User Guide*.

Remove Runtime Monitoring from all clusters. For more information, see [Removing Runtime Monitoring from an Amazon ECS cluster](ecs-guard-duty-remove-manual.md).