# Configuring Malware Protection for S3 for your bucket For Malware Protection for S3 to scan and (optionally) add tags to your S3 objects, you can use service roles that has the necessary permissions to perform malware scan actions on your behalf. For more information about using service roles to enable malware protection for S3, see [Service Access](https://docs.aws.amazon.com//guardduty/latest/ug/enable-malware-protection-s3-bucket.html#service-access-s3-malware-protection). This role is different from the [GuardDuty Malware Protection service-linked role](https://docs.aws.amazon.com//guardduty/latest/ug/using-service-linked-roles.html). If you prefer to use IAM roles, you can attach an IAM role that includes the required permissions to scan and (optionally) add tags to your S3 objects. GuardDuty then assumes this IAM role to perform these actions on your behalf. You will need this IAM role name at the time of enabling this protection plan for your Amazon S3 bucket. If you are using IAM roles, for each time you want to protect an Amazon S3 bucket, you must perform both the steps listed in this section. To enable Malware Protection for S3, you will need details such as S3 bucket name, object prefixes if you want to focus the protection for specific prefixes, and the IAM role name with required permissions. The steps remain the same whether you get started with Malware Protection for S3 independently or enable it as a part of the GuardDuty service. **Topics** 1. [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md) 1. [Enabling Malware Protection for S3 for your bucket](enable-malware-protection-s3-bucket.md) 1. [Troubleshooting IAM role permissions error](troubleshoot-malware-protection-s3-iam-role-permissions-error.md) # Enabling Malware Protection for S3 for your bucket This section provides detailed steps on how to enable Malware Protection for S3 for a bucket in your own account. Before you proceed, review the following considerations: + When you enable this protection plan using the GuardDuty console, it includes the step to create a new role or use an existing role under the **Service access** section. + When you enable this protection plan using the GuardDuty API or CLI, then you must [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md) before proceeding further. + Regardless of how you enable this protection plan, you must have the required [Permissions to create a Malware Protection plan resource](#malware-protection-s3-permissions-prerequisite). **Considering Amazon S3 bucket throttling** S3 Throttling might limit the rate at which data can be transferred to or from your Amazon S3 buckets. This can potentially delay malware scans of your newly uploaded objects. If you expect high volumes of `GET` and `PUT` requests to your S3 buckets, consider implementing measures to prevent throttling. For information on how to do this, see [Prevent Amazon S3 throttling](https://docs.aws.amazon.com/athena/latest/ug/performance-tuning-s3-throttling.html) in the *Amazon Athena User Guide*. **Topics** ## Permissions to create a Malware Protection plan resource When you enable Malware Protection for S3 for an Amazon S3 bucket, GuardDuty creates a Malware Protection plan resource that acts as an identifier for the bucket's protection plan. If you are not already using the [AWS managed policy: AmazonGuardDutyFullAccess\$1v2 (recommended)](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonGuardDutyFullAccess-v2), then you must add the following permissions to create this resource: + `guardDuty:CreateMalwareProtectionPlan` + `iam:PassRole` You can use the following custom policy example and replace the *placeholder values* with the values appropriate for your account: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "arn:aws:iam::111122223333:role/role-name", "Condition": { "StringEquals": { "iam:PassedToService": "malware-protection-plan.guardduty.amazonaws.com" } } }, { "Effect": "Allow", "Action": [ "guardduty:CreateMalwareProtectionPlan" ], "Resource": "*" } ] } ``` ------ ## Enabling Malware Protection for S3 by using GuardDuty console The following sections provide a step-by-step walkthrough as you will experience in the GuardDuty console. **To enable Malware Protection for S3 by using GuardDuty console** ### Enter S3 bucket details Use the following steps to provide the Amazon S3 bucket details: 1. Sign in to the AWS Management Console and open the GuardDuty console at [https://console.aws.amazon.com/guardduty/](https://console.aws.amazon.com/guardduty/). 1. By using the AWS Region selector in the upper-right corner of the page, select the Region where you want to enable Malware Protection for S3. 1. In the navigation pane, choose **Malware Protection for S3**. 1. In the **Protected buckets** section, choose **Enable** to enable Malware Protection for S3 for an S3 bucket that belongs to your own AWS account. 1. Under **Enter S3 bucket details**, enter the **Amazon S3 bucket** name. Alternatively, choose **Browse S3** to select an S3 bucket. The AWS Region of the S3 bucket and the AWS account where you enable Malware Protection for S3 must be the same. For example, if your account belongs to the `us-east-1` Region, then your Amazon S3 bucket Region must also be `us-east-1`. 1. Under **Prefix**, you can select either **All the objects in the S3 bucket** or **Objects beginning with a specific prefix**. + Select **All the objects in the S3 bucket** when you want GuardDuty can scan all the newly uploaded objects in the selected bucket. + Select **Objects beginning with a specific prefix** when you want scan the newly uploaded objects that belong to a specific prefix. This option helps you focus the scope of the malware scan on the selected object prefixes only. For more information about using prefixes, see [Organizing objects in Amazon S3 console by using folders](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-folders.html) in the *Amazon S3 User Guide*. Choose **Add prefix** and enter prefix. You can add up to five prefixes. ### Enable tagging for scanned objects This is an **optional** step. When you enable the tagging option before an object gets uploaded to your bucket, then after completing the scan, GuardDuty will add a predefined tag with key as `GuardDutyMalwareScanStatus` and the value as the scan result. To use Malware Protection for S3 optimally, we recommend to enable the option to add tag to the S3 objects after the scan ends. Standard S3 Object Tagging cost applies. For more information, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md). **Why should you enable tagging?** + Enabling tagging is one of the ways to know about the malware scan result. For information about an S3 malware scan result, see [Monitoring S3 object scans in Malware Protection for S3](monitoring-malware-protection-s3-scans-gdu.md). + Set up tag-based access control (TBAC) policy on your S3 bucket that contains the potentially malicious object. For information about considerations and how to implement tag-based access control (TBAC), see [Using tag-based access control (TBAC) with Malware Protection for S3](tag-based-access-s3-malware-protection.md). **Considerations for GuardDuty to add a tag to your S3 object:** + By default, you can associate up to 10 tags with an object. For more information, see [Categorizing your storage using tags](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html) in the *Amazon S3 User Guide*. If all 10 tags are already in use, GuardDuty can't add the predefined tag to the scanned object. GuardDuty also publishes the scan result to your default EventBridge event bus. For more information, see [Monitoring S3 object scans with Amazon EventBridge](monitor-with-eventbridge-s3-malware-protection.md). + When the selected IAM role doesn't include the permission for GuardDuty to tag the S3 object, then even with tagging enabled for your protected bucket, GuardDuty will be unable to add tag to this scanned S3 object. For more information about the required IAM role permission for tagging, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md). GuardDuty also publishes the scan result to your default EventBridge event bus. For more information, see [Monitoring S3 object scans with Amazon EventBridge](monitor-with-eventbridge-s3-malware-protection.md). **To select an option under **Tag scanned objects**** + When you **want** GuardDuty to add tags to your scanned S3 objects, select **Tag objects**. + When you **don't want** GuardDuty to add tags to your scanned S3 objects, select **Do not tag objects**. ### Service access Use the following steps to choose an existing service role or create a new service role that has the necessary permissions to perform malware scan actions on your behalf. These actions may include scanning the newly uploaded S3 objects and (optionally) adding tags to those objects. For information about the permissions that this role will have, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md). In the **Service access** section, you can do one of the following: 1. **Create and use a new service role** — You can use create a new service role that has the necessary permissions to perform malware scan. Under the **Role name** you can choose to use the name pre-populated by GuardDuty or enter a meaningful name of your choice to identify the role. For example `GuardDutyS3MalwareScanRole`. The Role name must be 1-64 characters. Valid characters are a-z, A-Z, 0-9, and '\$1=,.@-\$1' characters. 1. **Use an existing service role** — You can choose an existing service role from the **Service role name** list. 1. Under **Policy template** you can view the policy for your S3 bucket. Make sure that you entered or selected an S3 bucket in the **Enter S3 bucket** details section. 1. Under **Service role name** choose a service role from the list of service roles. You can make changes to the policy based on your requirements For more details on how you can create or update an IAM role, see [Create or update IAM role policy](https://docs.aws.amazon.com//guardduty/latest/ug/malware-protection-s3-iam-policy-prerequisite.html). For issues with IAM role permissions, see [Troubleshooting IAM role permissions error](troubleshoot-malware-protection-s3-iam-role-permissions-error.md). ### (Optional) Tag Malware Protection plan ID This is an optional step that helps you add tags to the Malware Protection plan resource that would get created for your S3 bucket resource. Each tag has two parts: A tag key and an optional tag value. For more information about tagging and its benefits, see [Tagging AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html). **To add tags to your Malware Protection plan resource** 1. Enter **Key** and an optional **Value** for the tag. Both tag key and tag value are case sensitive. For information about names of tag key and tag value, see [Tag naming limits and requirements](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html#tag-conventions). 1. To add more tags to your Malware Protection plan resource, choose **Add new tag** and repeat the previous step. You can add up to 50 tags to each resource. 1. Choose **Enable**. ## Enabling Malware Protection for S3 by using API/CLI This section includes the steps for when you want to enable Malware Protection for S3 programmatically in your AWS environment. This requires the IAM role Amazon Resource Name (ARN) that you created in this step - [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md). **To enable Malware Protection for S3 programmatically by using API/CLI** + **By using the API** Run the [CreateMalwareProtectionPlan](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_CreateMalwareProtectionPlan.html) to enable Malware Protection for S3 for a bucket that belongs to your own account. + **By using AWS CLI** Depending on how you want to enable Malware Protection for S3, the following list provides AWS CLI example commands for specific use case. When you run these commands, replace the *placeholder examples shown in red*, with the values that are appropriate for your account. **AWS CLI example commands** + Use the following AWS CLI command to enable Malware Protection for S3 for a bucket with no tagging for scanned S3 objects: ``` aws guardduty create-malware-protection-plan --role "arn:aws:iam::111122223333:role/role-name" --protected-resource "S3Bucket"={"BucketName"="amzn-s3-demo-bucket1"} ``` + Use the following AWS CLI command to enable Malware Protection for S3 for a bucket with specific object prefixes and no tagging for scanned S3 objects: ``` aws guardduty create-malware-protection-plan --role "arn:aws:iam::111122223333:role/role-name" --protected-resource '{"S3Bucket":{"BucketName":"amzn-s3-demo-bucket1", "ObjectPrefixes": ["Object1","Object1"]}}' ``` + Use the following AWS CLI command to enable Malware Protection for S3 for a bucket with scanned S3 object tagging enabled: ``` aws guardduty create-malware-protection-plan --role "arn:aws:iam::111122223333:role/role-name" --protected-resource "S3Bucket"={"BucketName"="amzn-s3-demo-bucket1"} --actions "Tagging"={"Status"="ENABLED"} ``` After you run these commands successfully, a unique Malware Protection plan ID will get generated. To perform actions such as updating or disabling the protection plan for your bucket, you will need this Malware Protection plan ID. For issues with IAM role permissions, see [Troubleshooting IAM role permissions error](troubleshoot-malware-protection-s3-iam-role-permissions-error.md). # Create or update IAM role policy For Malware Protection for S3 to scan and (optionally) add tags to your S3 objects, you can use service roles that has the necessary permissions to perform malware scan actions on your behalf. For more information about using service roles to enable malware protection for S3, see [Service Access](https://docs.aws.amazon.com//guardduty/latest/ug/enable-malware-protection-s3-bucket.html#service-access-s3-malware-protection). This role is different from the [GuardDuty Malware Protection service-linked role](https://docs.aws.amazon.com//guardduty/latest/ug/using-service-linked-roles.html). If you prefer to use IAM roles, you can attach an IAM role that includes the required permissions to scan and (optionally) add tags to your S3 objects. You must create an IAM role or update an existing role to include these permissions. Because these permissions are required for each Amazon S3 bucket for which you enable Malware Protection for S3, you need to perform this step for each Amazon S3 bucket that you to protect. The following list explains how certain permissions help GuardDuty perform the malware scan on your behalf: + Allow Amazon EventBridge actions to create and manage the EventBridge managed rule so that Malware Protection for S3 can listen to your S3 object notifications. For more information, see [Amazon EventBridge managed rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html#eb-rules-managed) in the *Amazon EventBridge User Guide*. + Allow Amazon S3 and EventBridge actions to send notification to EventBridge for all events in this bucket For more information, see [Enabling Amazon EventBridge](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-event-notifications-eventbridge.html) in the *Amazon S3 User Guide*. + Allow Amazon S3 actions to access the uploaded S3 object and add a predefined tag, `GuardDutyMalwareScanStatus`, to the scanned S3 object. When using an object prefix, add an `s3:prefix` condition on the targeted prefixes only. This prevents GuardDuty from accessing all the S3 objects in your bucket. + Allow KMS key actions to access the object before scanning and putting a test object on buckets with the supported DSSE-KMS and SSE-KMS encryption. **Note** This step is required each time you enable Malware Protection for S3 for a bucket in your account. If you already have an existing IAM role, you can update its policy to include the details of another Amazon S3 bucket resource. The [Adding IAM policy permissions](#attach-iam-policy-s3-malware-protection) topic provides an example on how to do this. Use the following policies to create or update an IAM role. **Topics** + [Adding IAM policy permissions](#attach-iam-policy-s3-malware-protection) + [Adding Trust relationship policy](#add-iam-trust-policy-s3-malware-protection) ## Adding IAM policy permissions You can choose to update the inline policy of an existing IAM role, or create a new IAM role. For information about the steps, see [Creating an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) or [Modifying a role permissions policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy) in the *IAM User Guide*. Add the following permissions template to your preferred IAM role. Replace the following placeholder values with appropriate values associated with your account: + For *amzn-s3-demo-bucket*, replace with your Amazon S3 bucket name. To use the same IAM role for more than one S3 bucket resource, update an existing policy as displayed in the following example: ``` ... ... "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*", "arn:aws:s3:::amzn-s3-demo-bucket2/*" ], ... ... ``` Make sure to add a comma (,) before adding a new ARN associated with the S3 bucket. Do this wherever you refer to an S3 bucket `Resource` in the policy template. + For *111122223333*, replace with your AWS account ID. + For *us-east-1*, replace with your AWS Region. + For *APKAEIBAERJR2EXAMPLE*, replace with your customer managed key ID. If your S3 bucket is encrypted by using an AWS KMS key, we add the relevant permissions if you choose the [Create a new role](https://docs.aws.amazon.com//guardduty/latest/ug/enable-malware-protection-s3-bucket.html) option when configuring malware protection for your bucket. ``` "Resource": "arn:aws:kms:us-east-1:111122223333:key/*" ``` **IAM role policy template** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Sid": "AllowManagedRuleToSendS3EventsToGuardDuty", "Effect": "Allow", "Action": [ "events:PutRule", "events:DeleteRule", "events:PutTargets", "events:RemoveTargets" ], "Resource": [ "arn:aws:events:us-east-1:111122223333:rule/DO-NOT-DELETE-AmazonGuardDutyMalwareProtectionS3*" ], "Condition": { "StringLike": { "events:ManagedBy": "malware-protection-plan.guardduty.amazonaws.com" } } }, { "Sid": "AllowGuardDutyToMonitorEventBridgeManagedRule", "Effect": "Allow", "Action": [ "events:DescribeRule", "events:ListTargetsByRule" ], "Resource": [ "arn:aws:events:us-east-1:111122223333:rule/DO-NOT-DELETE-AmazonGuardDutyMalwareProtectionS3*" ] }, { "Sid": "AllowPostScanTag", "Effect": "Allow", "Action": [ "s3:PutObjectTagging", "s3:GetObjectTagging", "s3:PutObjectVersionTagging", "s3:GetObjectVersionTagging" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, { "Sid": "AllowEnableS3EventBridgeEvents", "Effect": "Allow", "Action": [ "s3:PutBucketNotification", "s3:GetBucketNotification" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ] }, { "Sid": "AllowPutValidationObject", "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/malware-protection-resource-validation-object" ] }, { "Sid": "AllowCheckBucketOwnership", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ] }, { "Sid": "AllowMalwareScan", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, { "Sid": "AllowDecryptForMalwareScan", "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/APKAEIBAERJR2EXAMPLE", "Condition": { "StringLike": { "kms:ViaService": "s3.us-east-1.amazonaws.com" } } } ] } ``` ------ ## Adding Trust relationship policy Attach the following trust policy to your IAM role. For information about steps, see [Modifying a role trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "malware-protection-plan.guardduty.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ # Troubleshooting IAM role permissions error When enabling Malware Protection for S3, GuardDuty checks if your IAM service role has the necessary permissions to validate Amazon S3 bucket ownership. If these permissions are missing or incorrectly configured, you might get the following message: ``` "message": "The request was rejected because provided IAM role does not have the required permissions to validate S3 bucket ownership." "type": "InvalidInputException" ``` The following scenarios can help you troubleshoot this error: **Missing IAM role permissions** + The IAM role must have the required permissions to allow Malware Protection for S3 to assume the role. + GuardDuty validates the bucket ownership with the `"s3:ListBucket"` permission. This must be present in the IAM role that you use. For information about the permissions, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md). **IAM role availability** + When you create a new IAM role, allow a few minutes for the changes to reach eventual consistency before enabling Malware Protection for S3. If you attempt to enable the protection plan immediately after creating the role, the validation might fail. + For Infrastructure as Code (IaC) deployments, GuardDuty recommends declaring a resource dependency to ensure the IAM role reaches eventual consistency. For sample templates on how to do this, see [GuardDuty GitHub repository](https://github.com/aws-samples/guardduty-malware-protection/tree/main/cdk). **Cross-region enablement** Ensure your Amazon S3 bucket is in the same Region where you are enabling Malware Protection for S3 in GuardDuty.