# GuardDuty Malware Protection for S3
Malware Protection for S3 helps you detect potential presence of malware by scanning newly uploaded objects to your selected Amazon Simple Storage Service (Amazon S3) bucket. When an S3 object or a new version of an existing S3 object gets uploaded to your selected bucket, GuardDuty automatically starts a malware scan.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/uweeumMAif4)
**Two approaches to enable Malware Protection for S3**
You can enable Malware Protection for S3 when your AWS account enables the GuardDuty service and you use Malware Protection for S3 as a part of the overall GuardDuty experience, or when you want to use the Malware Protection for S3 feature by itself without enabling the GuardDuty service. When you enable Malware Protection for S3 by itself, the GuardDuty documentation refers to it as using Malware Protection for S3 as an independent feature.
**Considerations for using Malware Protection for S3 independently**
+ GuardDuty security findings – Detector ID is a unique identifier that is associated with your account in a Region. When you enable GuardDuty in one or more Regions in an account, a detector ID gets created automatically for this account in each Region where you enable GuardDuty. For more information, see *Detector* in the [Concepts and key terms in Amazon GuardDuty](guardduty_concepts.md) document.
When you enable Malware Protection for S3 independently in an account, that account will **not** have an associated detector ID. This impacts what GuardDuty features may be available to you. For example, when an S3 malware scan detects the presence of malware, no GuardDuty finding will get generated in your AWS account because all GuardDuty findings are associated with a detector ID.
+ Checking if the scanned object is malicious – By default, GuardDuty publishes the malware scan results to your default Amazon EventBridge event bus and an Amazon CloudWatch namespace. When you enable tagging at the time of enabling Malware Protection for S3 for a bucket, the scanned S3 object gets a tag that mentions the scan result. For more information about tagging, see [Optional tagging of objects based on scan result](how-malware-protection-for-s3-gdu-works.md#enable-optional-tagging-malware-protection-s3).
**General considerations for enabling Malware Protection for S3**
The following general consideration apply whether you use Malware Protection for S3 independently or as a part of the GuardDuty experience:
+ You can enable Malware Protection for S3 for an Amazon S3 bucket that belongs to your own account. As a delegated GuardDuty administrator account you can't enable this feature in an Amazon S3 bucket that belongs to a member account.
+ You can enable this feature in the S3 buckets that belong to the same Region that is currently selected in the GuardDuty console. GuardDuty doesn't support enabling this feature in cross-Region S3 buckets.
+ As a delegated GuardDuty administrator account, you will receive an Amazon EventBridge notification each time there is a change in the [Viewing and understanding protected bucket status](malware-protection-s3-bucket-status-gdu.md) of an S3 bucket that one of your organization's member account configured for this feature.
**Topics**
+ [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md)
+ [How does Malware Protection for S3 work?](how-malware-protection-for-s3-gdu-works.md)
+ [Capabilities of Malware Protection for S3](s3-malware-protection-capability.md)
+ [(Optional) Get started with GuardDuty Malware Protection for S3 independently (console only)](malware-protection-s3-get-started-independent.md)
+ [Configuring Malware Protection for S3 for your bucket](configuring-malware-protection-for-s3-guardduty.md)
+ [Steps after enabling Malware Protection for S3](malware-protection-s3-steps-after-enabling.md)
+ [On-demand S3 malware scan in GuardDuty](malware-protection-s3-on-demand.md)
+ [Using tag-based access control (TBAC) with Malware Protection for S3](tag-based-access-s3-malware-protection.md)
+ [Viewing and understanding protected bucket status](malware-protection-s3-bucket-status-gdu.md)
+ [Monitoring S3 object scans in Malware Protection for S3](monitoring-malware-protection-s3-scans-gdu.md)
+ [Troubleshooting](troubleshoot-s3-malware-protection.md)
+ [Editing Malware Protection plan for a protected bucket](edit-malware-protection-protected-s3-bucket.md)
+ [Disabling Malware Protection for S3 for a protected bucket](disable-malware-s3-protected-bucket.md)
+ [Supportability of Amazon S3 features](supported-s3-features-malware-protection-s3.md)
+ [Quotas in Malware Protection for S3](malware-protection-s3-quotas-guardduty.md)
# Pricing and usage cost for Malware Protection for S3
The pricing in Malware Protection for S3 works differently than other protection plans in GuardDuty. While most of the GuardDuty protection plans follow a 30-day short term free trial, Malware Protection for S3 follows 12 months Free Tier plan in AWS. For information about GuardDuty pricing, see [Pricing in GuardDuty](guardduty-pricing.md).
The following list provides the pricing costs associated with using Malware Protection for S3.
**Free Tier plan (scanning cost)**
Each AWS account gets a 12-month Free Tier that includes usage up to a specific limit per month for each Region. Each AWS account gets a monthly free tier usage up to 1,000 requests and 1 GB data scanned. If your usage goes beyond the specified limit, you will start incurring the usage cost for the exceeded limit. For complete pricing details, see [GuardDuty protection plans pricing](https://aws.amazon.com/guardduty/pricing/#GuardDuty_protection_plans).
On-demand scanning is not included in the free tier.
For information about the usage cost after enabling Malware Protection for S3, see [Reviewing usage cost for Malware Protection for S3Reviewing usage cost](usage-cost-malware-protection-s3-gdu.md).
**S3 Object Tagging usage cost**
When you enable Malware Protection for S3, it is optional to enable tagging for your scanned S3 objects. When you choose to enable S3 Object Tagging, there is an associated usage cost. For more information about the costs, see [Management & insights tab](https://aws.amazon.com/s3/pricing/) on the *Amazon S3 pricing page*.
S3 Object Tagging usage cost is **not included** in the Free Tier plan.
**Amazon S3 APIs - GET and PUT usage cost**
You will incur usage cost when GuardDuty runs the Amazon S3 APIs based on the IAM role. For example, after assuming the IAM role, GuardDuty runs the `PutObject` API to add the test object to your selected bucket. This helps GuardDuty assess the enabled status of the feature.
For information about pricing of S3 API calls in your AWS Region, see [Requests & data retrievals under the Storage & requests tab](https://aws.amazon.com/s3/pricing/#aws-element-86cbc19a-da4c-4c04-bb4f-5c4d1a2de09e) on the *Amazon S3 pricing page*.
# Reviewing usage cost for Malware Protection for S3
Your account starts incurring usage cost when you use Malware Protection for S3 beyond the specific limit under the Free Tier plan, or when your account's 12-month Free Tier plan ends. For information about the Free Tier plan, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md). Note that the free tier plan does not apply to Malware Protection for S3 on-demand object scanning.
The GuardDuty console doesn't support reviewing the Malware Protection for S3 usage cost. To view the usage cost, navigate to **Cost Explorer** in the [https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/) console. For information about AWS account billing, see the [AWS Billing User Guide](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-what-is.html).
For information about estimated usage cost in GuardDuty, see [Monitoring usage and estimating costs](monitoring_costs.md).
# How does Malware Protection for S3 work?
This section describes components of Malware Protection for S3, how it works after you enable it for an S3 bucket, and how you can review the malware scan status and result.
## Overview
You can enable Malware Protection for S3 for an Amazon S3 bucket that belongs to your own AWS account. GuardDuty provides you flexibility to enable this feature for your entire bucket, or limit the scope of the malware scan to specific [object prefixes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html) where GuardDuty scans each uploaded object that starts with one of the selected prefixes. You can add up to 5 prefixes. When you enable the feature for an S3 bucket, then that bucket is called a **protected bucket**.
## IAM role permissions
Malware Protection for S3 uses an IAM role that permits GuardDuty to perform the malware scan actions on your behalf. These actions include being notified of the newly uploaded objects in your selected bucket, scanning those objects, and optionally adding tags to your scanned objects. This is a prerequisite to configuring your S3 bucket with this feature.
You have the option to either update an existing IAM role, or create a new role for this purpose. When you enable Malware Protection for S3 for more than one bucket, you can update the existing IAM role to include the other bucket name, as needed. For more information, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md).
## Optional tagging of objects based on scan result
At the time of enabling Malware Protection for S3 for your bucket, there is an optional step to enable tagging for scanned S3 objects. The IAM role already includes the permission to add tags to your object after the scan. However, GuardDuty will add tags only when you enable this option at the time of setup.
You must enable this option before an object gets uploaded. After the scan ends, GuardDuty adds a predefined tag to the scanned S3 object with the following key:value pair:
`GuardDutyMalwareScanStatus`:`Potential scan result`
The potential scan result tag values include `NO_THREATS_FOUND`, `THREATS_FOUND`, `UNSUPPORTED`, `ACCESS_DENIED`, and `FAILED`. For more information about these values, see [S3 object potential scan status and result status](monitoring-malware-protection-s3-scans-gdu.md#s3-object-scan-result-value-malware-protection).
Enabling tagging is one of the ways to know about the S3 object scan result. You can further use these tags to add a tag-based access control (TBAC) S3 resource policy so that you can take actions on the potentially malicious objects. For more information, see [Adding TBAC on S3 bucket resource](tag-based-access-s3-malware-protection.md#apply-tbac-s3-malware-protection).
We recommend you to enable tagging at the time of configuring Malware Protection for S3 for your bucket. If you enable tagging after an object gets uploaded and potentially the scan initiates, GuardDuty will not be able to add tags to the scanned object. For information about associated S3 Object Tagging cost, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md).
## Process after you enable Malware Protection for S3 for a bucket
After you enable Malware Protection for S3, a **Malware Protection plan resource** gets created exclusively for the selected S3 bucket. This resource is associated with a Malware Protection plan ID, a unique identifier for your protected resource. By using one of the IAM permissions, GuardDuty then creates and manages an EventBridge managed rule by the name of `DO-NOT-DELETE-AmazonGuardDutyMalwareProtectionS3*`.
### How GuardDuty handles your data - guardrails for data protection
Malware Protection for S3 listens to the Amazon EventBridge notifications. When an object gets uploaded to the selected bucket or one of the prefixes, GuardDuty downloads that object from S3 bucket by using an [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html) and then reads, decrypts, and scans it in an isolated environment in the same Region. The scanning environment runs in a locked down virtual private cloud (VPC) with no internet access. The VPC is attached to a DNS Firewall rule group that allows communication only to the allowslisted domains that AWS owns. For the duration of the scan, GuardDuty temporarily stores the downloaded S3 object within the scanning environment that is encrypted with [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) keys.
**Note**
By default, all the Amazon S3 APIs listed under the [Object Created Event type](https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventBridge.html) in the *Amazon S3 User Guide*, will initiate the Malware Protection for S3 scan.
These *Event types* include [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html), [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html), [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html), and [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html).
For information about GuardDuty malware detection methodology and the scan engines that it uses, see [GuardDuty malware detection scan engine](guardduty-malware-detection-scan-engine.md).
After the malware scan completes, GuardDuty processes the scan metadata with the scan status and then deletes the downloaded copy of the object.
GuardDuty cleans the scanning environment each time before a new scan begins. GuardDuty uses contingent authorization for operator access to the scanning environment, and every access request is reviewed, approved, and audited.
### Reviewing S3 object scan status and result
GuardDuty publishes the S3 object scan result event to Amazon EventBridge default event bus. GuardDuty also sends the scan metrics such as number of objects scanned and bytes scanned to Amazon CloudWatch. If you enabled tagging, then GuardDuty will add the predefined tag `GuardDutyMalwareScanStatus` and a potential scan result as the tag value.
**Important**
GuardDuty uses at-least-once delivery, which means you might receive multiple scan results for the same object. We recommend designing your applications to handle duplicate results. You're billed only once for each scanned object.
For more information, see [Monitoring S3 object scans in Malware Protection for S3](monitoring-malware-protection-s3-scans-gdu.md).
### Reviewing generated findings
Reviewing the findings depends on whether or not you are using Malware Protection for S3 with GuardDuty. Consider the following scenarios:
**Using Malware Protection for S3 when you have GuardDuty service enabled (detector ID)**
If the malware scan detects a potentially malicious file in an S3 object, GuardDuty will generate an associated finding. You can view the finding details and use the recommended steps to potentially remediate the finding. Based on your [Export findings frequency](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_exportfindings.html#guardduty_exportfindings-frequency), the generated finding gets exported to an S3 bucket and EventBridge event bus.
For information about the finding type that would get generated, see [Malware Protection for S3 finding type](gdu-malware-protection-s3-finding-types.md).
**Using Malware Protection for S3 as an independent feature (no detector ID)**
GuardDuty will not be able to generate findings because there is no associated detector ID. To know the S3 object malware scan status, you can view the scan result that GuardDuty automatically publishes to your default event bus. You can also view the CloudWatch metrics to assess the number of objects and bytes that GuardDuty attempted to scan. You can set up CloudWatch alarms to get notified about the scan results. If you have enabled S3 Object Tagging, you can also view the malware scan status by checking the S3 object for the `GuardDutyMalwareScanStatus` tag key and the scan result tag value.
For information about the S3 object scan status and result, see [Monitoring S3 object scans in Malware Protection for S3](monitoring-malware-protection-s3-scans-gdu.md).
# Capabilities of Malware Protection for S3
The following list provides an overview of what you can expect or do after enabling Malware Protection for S3 for your bucket:
+ **Choose what to scan** – Scan files as they get uploaded to all or specific prefixes (up to 5) associated with your selected S3 bucket.
+ **Automatic scans on uploaded objects** – Once you enable Malware Protection for S3 for a bucket, GuardDuty will automatically start a scan to detect potential malware in a newly uploaded object.
+ **On-demand scans** – You can initiate scans for existing objects or re-scan previously scanned objects. For more information, see [On-demand S3 malware scan in GuardDuty](malware-protection-s3-on-demand.md).
+ **Enable through console, by using API/AWS CLI, or CloudFormation** – Choose a preferred method to enable Malware Protection for S3.
You can enable Malware Protection for S3 by using Infrastructure as code (IaC) platforms such as *Terraform*. For more information, see [Resource: `aws_guardduty_malware_protection_plan`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_malware_protection_plan).
+ **Supported file formats, Malware Protection for S3 quotas, and Amazon S3 features** – Malware Protection for S3 supports all file formats that you can upload to an S3 bucket. If the uploaded file is password-protected and GuardDuty is able to detect the presence of password protection for the uploaded file's type, then GuardDuty will attempt to scan the original content using common passwords. If the password fails, the scan will be skipped. GuardDuty can't detect the presence of password protection on all file formats. If GuardDuty can't detect the presence of password protection, then GuardDuty will still scan the encrypted content.
For information about the quotas related to object size, maximum archive depth level, and other details, see [Quotas in Malware Protection for S3](malware-protection-s3-quotas-guardduty.md).
For information about whether or not an Amazon S3 feature is supported, see [Supportability of Amazon S3 features](supported-s3-features-malware-protection-s3.md).
+ **Supports tagging scanned S3 object** – When you enable [Optional tagging of objects based on scan result](how-malware-protection-for-s3-gdu-works.md#enable-optional-tagging-malware-protection-s3), then after each malware scan, GuardDuty will add a tag that indicates the scan status. You can use this tag to set up tag-based access control (TBAC) for the S3 objects. For example, you can restrict access to the S3 objects that are indicated as malicious and have the tag value as `THREATS_FOUND`.
+ **Amazon EventBridge notifications** – GuardDuty sends events to Amazon EventBridge when the Malware Protection plan resource status changes, or a malware scan of the S3 object completes. These events are sent to the default event bus. You can use EventBridge and these events to write rules that take actions, such as monitoring when these events happen. For more information, see [Monitoring S3 object scans with Amazon EventBridge](monitor-with-eventbridge-s3-malware-protection.md).
+ **CloudWatch metrics** – View CloudWatch metrics to enable alarms on certain malware scan status. For more information, see [S3 object scan status metrics in CloudWatch](monitor-cloudwatch-metrics-s3-malware-protection.md).
# (Optional) Get started with GuardDuty Malware Protection for S3 independently (console only)
Use this optional step when you want to get started with Malware Protection for S3 threat detection option independent of the GuardDuty status in your AWS account.
If you also want to use other dedicated protection plans in GuardDuty, you must get started with the Amazon GuardDuty service. For information about GuardDuty protection plans, see [Features of GuardDuty](what-is-guardduty.md#features-of-guardduty). When you have already enabled GuardDuty in your account, then you can skip this step and continue with [Configuring Malware Protection for S3 for your bucket](configuring-malware-protection-for-s3-guardduty.md).
**Steps to get started with Malware Protection for S3 only threat detection**
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. Select **GuardDuty Malware Protection for S3 only**. This helps you detect if a newly uploaded file in your Amazon Simple Storage Service (Amazon S3) bucket potentially contains malware.
![\[Selecting GuardDuty Malware Protection for S3 only option and then choosing Get started.\]](http://docs.aws.amazon.com/guardduty/latest/ug/images/select-malware-protection-for-s3-console.png)
1. Choose **Get started**. You can now continue with steps under [Configuring Malware Protection for S3 for your bucket](configuring-malware-protection-for-s3-guardduty.md).
# 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.
# Steps after enabling Malware Protection for S3
This section lists the steps that you may take after enabling Malware Protection for S3 for a bucket. The following steps are listed in an order that will help you navigate through the next steps:
**To follow after you enable Malware Protection for S3 for your bucket**
1. **Add tag-based access control (TBAC) resource policy** – When you enable tagging, then before an object gets uploaded to your selected bucket, ensure to add the TBAC policy to your S3 bucket resource. For more information, see [Adding TBAC on S3 bucket resource](tag-based-access-s3-malware-protection.md#apply-tbac-s3-malware-protection).
1. **Monitor Malware Protection plan status** – Monitor the **Status** column for each protected bucket. For information about potential statuses and what they mean, see [Viewing and understanding protected bucket status](malware-protection-s3-bucket-status-gdu.md).
1. **Start a scan** by choosing one of the following options:
+ **Upload an object**:
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Upload a file to the S3 bucket or the object prefix for which you enabled this feature. For steps to upload a file, see [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html) in the *Amazon S3 User Guide*.
+ **Initiate an on-demand scan**: [On-demand S3 malware scan in GuardDuty](malware-protection-s3-on-demand.md)
1. **Monitor S3 object scan status and scan result** – This step includes information about how to check the malware scan status of the S3 object.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/guardduty/latest/ug/malware-protection-s3-steps-after-enabling.html)
# On-demand S3 malware scan in GuardDuty
GuardDuty Malware Protection for S3 continuously monitors new S3 uploads. For objects that existed before enabling protection, or to re-scan previously scanned objects, you can initiate on-demand S3 malware scan once you've enabled the GuardDuty Malware Protection plan for your bucket.
On-demand malware scanning uses the Malware Protection Plan's IAM role for object access and applying configuration. The scan will override any prefix configured in the Malware Protection Plan for the bucket.
**Note**
The Malware Protection for S3 quota applies to on-demand malware scanning. For more information, See [Quotas in Malware Protection for S3](malware-protection-s3-quotas-guardduty.md).
For more information about pricing, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md).
## Prerequisites
Before you start an on-demand malware scan, your account must meet the following prerequisites:
+ Malware Protection for S3 is enabled on the target bucket. See [Configuring Malware Protection for S3 for your bucket](configuring-malware-protection-for-s3-guardduty.md) for more information.
+ The [AWS managed policy: AmazonGuardDutyFullAccess\$1v2 (recommended)](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonGuardDutyFullAccess-v2) policy is attached to the IAM user or the IAM role invoking the API.
## Start on-demand malware scan
Use the [SendObjectMalwareScan](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_SendObjectMalwareScan.html) API operation, which requires the S3 object path as input.
------
#### [ API/CLI ]
You can scan either the latest version of the object or specify a particular version to scan.
To scan a specific version of an object:
```
aws guardduty send-object-malware-scan --s3-object '{"Bucket": "amzn-s3-demo-bucket", "Key": "APKAEIBAERJR2EXAMPLE", "VersionId": "d41d8cd98f00b204e9800998eEXAMPLE"}'
```
To scan the latest version of an object:
```
aws guardduty send-object-malware-scan --s3-object '{"Bucket": "amzn-s3-demo-bucket", "Key": "APKAEIBAERJR2EXAMPLE"}'
```
------
**Important**
A successful API call confirms that the scan request has been accepted. However, it is important to monitor the scan results to ensure successful completion and to identify any issues, such as errors accessing the object. For more information, see [Monitoring S3 object scans in Malware Protection for S3](monitoring-malware-protection-s3-scans-gdu.md).
# Using tag-based access control (TBAC) with Malware Protection for S3
When enabling Malware Protection for S3 for your bucket, you can optionally choose to enable tagging. After attempting to scan a newly uploaded S3 object in the selected bucket, GuardDuty adds a tag to the scanned object to provide the malware scan status. There is a direct usage cost associated when you enable tagging. For more information, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md).
GuardDuty uses a predefined tag with the key as `GuardDutyMalwareScanStatus` and the value as one of the malware scan statuses. For information about these values, see [S3 object potential scan status and result status](monitoring-malware-protection-s3-scans-gdu.md#s3-object-scan-result-value-malware-protection).
**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).
## Adding TBAC on S3 bucket resource
You can use the S3 bucket resource policies to manage tag-based access control (TBAC) for your S3 objects. You can provide access to specific users to access and read the S3 object. If you have an organization that was created by using AWS Organizations, you must enforce that no one can modify the tags added by GuardDuty. For more information, see [Preventing tags from being modified except by authorized principals](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps_examples_tagging.html#example-require-restrict-tag-mods-to-admin) in the *AWS Organizations User Guide*. The example used in the linked topic mentions `ec2`. When you use this example, replace *ec2* with `s3`.
The following list explains what you can do by using TBAC:
+ Prevent all the users except Malware Protection for S3 service principal from reading the S3 objects that are not yet tagged with the following tag key-value pair:
`GuardDutyMalwareScanStatus`:`Potential key value`
+ Allow only GuardDuty to add the tag key `GuardDutyMalwareScanStatus` with value as the scan result, to a scanned S3 object. The following policy template can allow specific users that have access, to potentially override the tag key-value pair.
**Example S3 bucket resource policy:**
Replace the following placeholder values in the example policy:
+ *IAM-role-name* - Provide the IAM role that you used for configuring Malware Protection for S3 in your bucket.
+ *555555555555* - Provide the AWS account associated with the protected bucket.
+ *amzn-s3-demo-bucket* - Provide the protected bucket name.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "NoReadUnlessClean",
"Effect": "Deny",
"NotPrincipal": {
"AWS": [
"arn:aws:sts::555555555555:assumed-role/IAM-role-name/GuardDutyMalwareProtection",
"arn:aws:iam::555555555555:role/IAM-role-name"
]
},
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Condition": {
"StringNotEquals": {
"s3:ExistingObjectTag/GuardDutyMalwareScanStatus": "NO_THREATS_FOUND"
}
}
},
{
"Sid": "OnlyGuardDutyCanTagScanStatus",
"Effect": "Deny",
"NotPrincipal": {
"AWS": [
"arn:aws:sts::555555555555:assumed-role/IAM-role-name/GuardDutyMalwareProtection",
"arn:aws:iam::555555555555:role/IAM-role-name"
]
},
"Action": "s3:PutObjectTagging",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Condition": {
"ForAnyValue:StringEquals": {
"s3:RequestObjectTagKeys": "GuardDutyMalwareScanStatus"
}
}
}
]
}
```
------
For more information about tagging your S3 resource, [Tagging and access control policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/tagging-and-policies.html).
# Viewing and understanding protected bucket status
After enabling Malware Protection for S3 for a bucket, the status indicates whether the feature is configured and functional as expected. This status is associated with a unique Malware Protection plan identifier (ID). GuardDuty creates this ID at the time of enabling the feature.
Use the following procedure to view the status of your protected bucket:
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. In the navigation pane, select **Malware Protection for S3**.
1. In the **Protected buckets** table, view the corresponding **Status** column for your **S3 bucket**.
The following table lists and describes status values associated with your Malware Protection plan resource. By understanding what these statuses mean for your protected bucket, you can better ensure that GuardDuty initiates an automatic malware scan when an object gets uploaded.
| Status | Description |
| --- | --- |
| Active | Your S3 bucket has been configured with Malware Protection for S3 successfully. When the status is *Active*, changes to the IAM role (deletion or permissions modification) won't update the status to *Warning* or *Error*. We recommend monitoring the scan status continuously by using any of the methods described in [Monitoring S3 object scans](monitoring-malware-protection-s3-scans-gdu.md). |
| Warning**[*](#fix-protection-status-s3-malware)** | Malware Protection for S3 is designed to not get impacted when a warning shows up. When GuardDuty notices a new S3 object, it will initiate a malware scan. After initiating the scan successfully, the **Status** column value may take a few minutes to change to **Active**. You will receive an EventBridge notification after the **Status** column value updates. |
| Error**[*](#fix-protection-status-s3-malware)** | Your bucket is not protected. None of the malware scans associated with this S3 bucket will complete. There could be one or more potential root causes. |
**\$1**For information about potential issues and the corresponding steps to resolve them, see [Troubleshooting Malware Protection plan status](troubleshoot-s3-malware-protection-status-errors.md).
# Monitoring S3 object scans in Malware Protection for S3
When using Malware Protection for S3 with a GuardDuty detector ID, if your Amazon S3 object is potentially malicious, GuardDuty will generate [Malware Protection for S3 finding type](gdu-malware-protection-s3-finding-types.md). Using the GuardDuty console and APIs, you can view the generated findings. For information about understanding this finding type, see [Finding details](guardduty_findings-summary.md).
When using Malware Protection for S3 without enabling GuardDuty (no detector ID), even when your scanned Amazon S3 object is potentially malicious, GuardDuty can't generate any findings.
**Topics**
+ [S3 object potential scan status and result status](#s3-object-scan-result-value-malware-protection)
+ [Monitoring S3 object scans with Amazon EventBridge](monitor-with-eventbridge-s3-malware-protection.md)
+ [Monitoring S3 object scans with GuardDuty managed tags](monitor-enable-s3-object-tagging-malware-protection.md)
+ [S3 object scan status metrics in CloudWatch](monitor-cloudwatch-metrics-s3-malware-protection.md)
## S3 object potential scan status and result status
This section explains the potential S3 object scan status values and the scan result values.
An S3 object scan status indicates the status of the malware scan, such as completed, skipped, or failed.
An S3 object malware scan result status indicates the result of the scan based on the scan status value. Each malware scan result status value maps to a scan status.
The following list provides the potential S3 object scan result values. If you have enabled tagging, you can monitor the scan result by [Using S3 Object Tags](monitor-enable-s3-object-tagging-malware-protection.md). After the scan, the tag value will have one of the following scan result values.
**S3 object potential malware scan result status values**
+ `NO_THREATS_FOUND` – GuardDuty detected no potential threat associated with the scanned object.
+ `THREATS_FOUND` – GuardDuty detected a potential threat associated with the scanned object.
+ `UNSUPPORTED` – There are a few reasons why Malware Protection for S3 will skip a scan. Potential reasons include password-protected file, archives with extremely high compression ratios, [Malware Protection for S3 quotas](malware-protection-s3-quotas-guardduty.md), and support for certain Amazon S3 features may be unavailable. For more information, see [Capabilities of Malware Protection for S3](s3-malware-protection-capability.md).
+ `ACCESS_DENIED` – GuardDuty can't access this object for scanning. Check the IAM role permissions associated with this bucket. For more information, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md).
If you have enabled post-scan S3 object tagging, see [Troubleshooting S3 object post-scan tag failures](troubleshoot-s3-post-scan-tag-failures.md).
+ `FAILED` – GuardDuty can't perform malware scan on this object because of an internal error.
The following list provides potential S3 object scan status values and their mapping to the S3 object scan result.
**S3 object potential scan status values**
+ **Completed** – The scan completed successfully and indicates whether the S3 object has malware. In this case, the potential S3 object scan result value could be either `THREATS_FOUND` or `NO_THREATS_FOUND`.
+ **Skipped** – GuardDuty skips a malware scan when scanning this S3 object is not supported by Malware Protection for S3, or GuardDuty doesn't have access to the uploaded S3 object in the selected bucket.
In this case, the potential S3 object scan result value could be either `UNSUPPORTED` or `ACCESS_DENIED`.
GuardDuty will also skip the scan if the required IAM role gets deleted.
+ **Failed** – Similar to the S3 object scan result value `FAILED`, this scan status means that GuardDuty was unable to perform malware scan on the S3 object because of an internal error.
When the scan status is `SKIPPED`, the EventBridge notification for the S3 object scan result includes a `statusReasons` field within `scanResultDetails`. This field is a list of strings that provides the specific reason why the scan was skipped. The following table describes the possible `statusReasons` values.
| Status reason | Scan result status | Description |
| --- | --- | --- |
| `UNAUTHORIZED_TO_GET_OBJECT` | `ACCESS_DENIED` | Malware Protection for S3 doesn't have permission to read the S3 object, or the S3 object does not exist. Verify that the IAM role associated with the protected bucket has the required permissions and any bucket AWS KMS policy allows the role to decrypt objects. |
| `UNAUTHORIZED_TO_ASSUME_ROLE` | `ACCESS_DENIED` | Malware Protection for S3 can't assume the IAM role configured for the protected bucket. Verify that the role trust policy allows Malware Protection for S3 to assume the role. |
| `SSE_C_ENCRYPTED_OBJECT` | `ACCESS_DENIED` | The S3 object is encrypted with a customer-provided encryption key (SSE-C). GuardDuty can't access objects encrypted with SSE-C. For more information, see [Supportability of Amazon S3 features](supported-s3-features-malware-protection-s3.md). |
| `OBJECT_E_TAG_CHANGED` | `ACCESS_DENIED` | The S3 object ETag changed between the time the scan was initiated and when GuardDuty attempted to read the object. The subsequent upload or new version will be scanned. |
| `BUCKET_NOT_FOUND` | `ACCESS_DENIED` | The S3 bucket associated with the scan no longer exists. |
| `UNSUPPORTED_STORAGE_CLASS` | `UNSUPPORTED` | The S3 object uses a storage class that is not supported by Malware Protection for S3. For more information, see [Supportability of Amazon S3 features](supported-s3-features-malware-protection-s3.md). |
| `OBJECT_SIZE_LIMIT_EXCEEDED` | `UNSUPPORTED` | The S3 object size exceeds the maximum file size limit for Malware Protection for S3. For more information, see [Malware Protection for S3 quotas](malware-protection-s3-quotas-guardduty.md). |
| `PASSWORD_PROTECTED` | `UNSUPPORTED` | The object is password-protected. |
| `EXTRACTED_FILE_LIMIT_EXCEEDED` | `UNSUPPORTED` | The archive contains more files than the maximum allowed limit. For more information, see [Malware Protection for S3 quotas](malware-protection-s3-quotas-guardduty.md). |
| `EXTRACTED_LEVEL_LIMIT_EXCEEDED` | `UNSUPPORTED` | The archive exceeds the maximum nesting depth allowed. |
| `EXTRACTED_BYTE_LIMIT_EXCEEDED` | `UNSUPPORTED` | The extracted archive content exceeds the maximum byte size allowed. For more information, see [Malware Protection for S3 quotas](malware-protection-s3-quotas-guardduty.md). |
| `EXTRACTION_RATIO_LIMIT_EXCEEDED` | `UNSUPPORTED` | The archive has an extremely high compression ratio that exceeds the allowed limit. For more information, see [Malware Protection for S3 quotas](malware-protection-s3-quotas-guardduty.md). |
# Monitoring S3 object scans with Amazon EventBridge
*Amazon EventBridge* is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources. EventBridge delivers a stream of real-time data from your own applications, Software-as-a-Service (SaaS) applications, and AWS services and routes that data to targets such as Lambda. This enables you to monitor events that happen in services, and build event-driven architectures. For more information, see the [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
As the owner account of an S3 bucket that is protected with Malware Protection for S3, GuardDuty publishes EventBridge notifications to the default event bus in the following scenarios:
+ **Malware Protection plan resource status** changes for any of your protected buckets. For information about various statuses, see [Viewing and understanding protected bucket status](malware-protection-s3-bucket-status-gdu.md).
For setting up Amazon EventBridge (EventBridge) rule for the resource status, see [Malware Protection plan resource status](#resource-status-malware-protection-s3-ev).
+ The **S3 object scan result** gets published to your default EventBridge event bus.
The `s3Throttled` field indicates whether or not there was a delay in uploading or retrieving storage from Amazon S3. The value `true` indicates that there was a delay, and `false` indicates that there was no delay.
If `s3Throttled` is `true` for your scan result, then Amazon S3 recommends setting up prefixes in a way that helps you reduce the transactions per second (TPS) for each prefix. For more information, see [Best practices design patterns: optimizing Amazon S3 performance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html) in the *Amazon S3 User Guide*.
For setting up Amazon EventBridge (EventBridge) rule for the S3 object scan results, see [S3 object scan result](#s3-object-scan-status-malware-protection-s3-ev).
+ There is a **post-scan tag failure event** because of the following reasons:
+ Your IAM role is missing permissions to tag the object.
The [Adding IAM policy permissions](malware-protection-s3-iam-policy-prerequisite.md#attach-iam-policy-s3-malware-protection) template includes the permission for GuardDuty to tag an object.
+ The bucket resource or object specified in the IAM role no longer exists.
+ The associated S3 object has already reached the maximum tag limit. For more information about the tag limit, see [Categorizing your storage using tags](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html) in the *Amazon S3 User Guide*.
For setting up Amazon EventBridge (EventBridge) rule for the post-scan tag failure events, see [Post-scan tag failure events](#post-tag-failure-malware-protection-s3-ev).
## Set up EventBridge rules
You can set up EventBridge rules in your account to send either resource status, post-scan tag failure events, or the S3 object scan result to another AWS service. As a delegated GuardDuty administrator account, you will receive the Malware Protection plan resource status notification when there is a change in the status.
Standard EventBridge pricing will apply. For more information, see [Amazon EventBridge pricing](https://aws.amazon.com/eventbridge/pricing/).
All the values that show up in *red* are placeholders for the example. These values will change based on the values in your account, and whether or not malware is detected.
**Topics**
+ [Malware Protection plan resource status](#resource-status-malware-protection-s3-ev)
+ [S3 object scan result](#s3-object-scan-status-malware-protection-s3-ev)
+ [Post-scan tag failure events](#post-tag-failure-malware-protection-s3-ev)
### Malware Protection plan resource status
You can create an EventBridge event pattern based on the following scenarios:
**Potential `detail-type` values**
+ `"GuardDuty Malware Protection Resource Status Active"`
+ `"GuardDuty Malware Protection Resource Status Warning"`
+ `"GuardDuty Malware Protection Resource Status Error"`
**Event pattern**
```
{
"detail-type": ["potential detail-type"],
"source": ["aws.guardduty"]
}
```
**Sample notification schema for `GuardDuty Malware Protection Resource Status Active`**:
```
{
"version": "0",
"id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
"detail-type": "GuardDuty Malware Protection Resource Status Active",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2017-12-22T18:43:48Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"eventTime": "2024-02-28T01:01:01Z",
"s3BucketDetails": {
"bucketName": "amzn-s3-demo-bucket"
},
"resourceStatus": "ACTIVE"
}
}
```
**Sample notification schema for `GuardDuty Malware Protection Resource Status Warning`**:
```
{
"version": "0",
"id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
"detail-type": "GuardDuty Malware Protection Resource Status warning",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2017-12-22T18:43:48Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"eventTime": "2024-02-28T01:01:01Z",
"s3BucketDetails": {
"bucketName": "amzn-s3-demo-bucket"
},
"resourceStatus": "WARNING",
"statusReasons": [
{
"code": "INSUFFICIENT_TEST_OBJECT_PERMISSIONS"
}
]
}
}
```
**Sample notification schema for `GuardDuty Malware Protection Resource Status Error`**:
```
{
"version": "0",
"id": "fc7a35b7-83bd-3c1f-ecfa-1b8de9e7f7d2",
"detail-type": "GuardDuty Malware Protection Resource Status Error",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2017-12-22T18:43:48Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"eventTime": "2024-02-28T01:01:01Z",
"s3BucketDetails": {
"bucketName": "amzn-s3-demo-bucket"
},
"resourceStatus": "ERROR",
"statusReasons": [
{
"code": "EVENTBRIDGE_MANAGED_EVENTS_DELIVERY_DISABLED"
}
]
}
}
```
Based on the reason behind the `resourceStatus` `ERROR`, the `statusReasons` value will get populated.
For information about troubleshooting steps for the following warning and errors, see [Troubleshooting Malware Protection plan status](troubleshoot-s3-malware-protection-status-errors.md).
### S3 object scan result
```
{
"detail-type": ["GuardDuty Malware Protection Object Scan Result"],
"source": ["aws.guardduty"]
}
```
When the `scanStatus` is `SKIPPED`, the `scanResultDetails` includes a `statusReasons` field that provides the specific reason why the scan was skipped. For information about the possible values, see [S3 object potential scan status and result status](monitoring-malware-protection-s3-scans-gdu.md#s3-object-scan-result-value-malware-protection).
**Sample notification schema for `NO_THREATS_FOUND`**:
```
{
"version": "0",
"id": "72c7d362-737a-6dce-fc78-9e27a0171419",
"detail-type": "GuardDuty Malware Protection Object Scan Result",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-02-28T01:01:01Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"scanStatus": "COMPLETED",
"resourceType": "S3_OBJECT",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "APKAEIBAERJR2EXAMPLE",
"eTag": "ASIAI44QH8DHBEXAMPLE",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"scanResultDetails": {
"scanResultStatus": "NO_THREATS_FOUND",
"threats": null,
"statusReasons": null
}
}
}
```
**Sample notification schema for `THREATS_FOUND`**:
```
{
"version": "0",
"id": "72c7d362-737a-6dce-fc78-9e27a0171419",
"detail-type": "GuardDuty Malware Protection Object Scan Result",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-02-28T01:01:01Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"scanStatus": "COMPLETED",
"resourceType": "S3_OBJECT",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "APKAEIBAERJR2EXAMPLE",
"eTag": "ASIAI44QH8DHBEXAMPLE",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"scanResultDetails": {
"scanResultStatus": "THREATS_FOUND",
"threats": [
{
"name": "EICAR-Test-File (not a virus)"
}
],
"statusReasons": null
}
}
}
```
**Note**
The `scanResultDetails.Threats` field contains only one threat. By default, the Malware Protection for S3 scan reports the first detected threat. After this, the `scanStatus` is set to `COMPLETED`.
**Sample notification schema for scan result status `UNSUPPORTED` (Skipped)**:
```
{
"version": "0",
"id": "72c7d362-737a-6dce-fc78-9e27a0EXAMPLE",
"detail-type": "GuardDuty Malware Protection Object Scan Result",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-02-28T01:01:01Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"scanStatus": "SKIPPED",
"resourceType": "S3_OBJECT",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "APKAEIBAERJR2EXAMPLE",
"eTag": "ASIAI44QH8DHBEXAMPLE",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"scanResultDetails": {
"scanResultStatus": "UNSUPPORTED",
"threats": null,
"statusReasons": ["PASSWORD_PROTECTED"]
}
}
}
```
**Sample notification schema for scan result status `ACCESS_DENIED` (Skipped)**:
```
{
"version": "0",
"id": "72c7d362-737a-6dce-fc78-9e27a0EXAMPLE",
"detail-type": "GuardDuty Malware Protection Object Scan Result",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-02-28T01:01:01Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"scanStatus": "SKIPPED",
"resourceType": "S3_OBJECT",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "APKAEIBAERJR2EXAMPLE",
"eTag": "ASIAI44QH8DHBEXAMPLE",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"scanResultDetails": {
"scanResultStatus": "ACCESS_DENIED",
"threats": null,
"statusReasons": ["SSE_C_ENCRYPTED_OBJECT"]
}
}
}
```
**Sample notification schema for scan result status `FAILED`**:
```
{
"version": "0",
"id": "72c7d362-737a-6dce-fc78-9e27a0EXAMPLE",
"detail-type": "GuardDuty Malware Protection Object Scan Result",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-02-28T01:01:01Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"scanStatus": "FAILED",
"resourceType": "S3_OBJECT",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "APKAEIBAERJR2EXAMPLE",
"eTag": "ASIAI44QH8DHBEXAMPLE",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"scanResultDetails": {
"scanResultStatus": "FAILED",
"threats": null,
"statusReasons": null
}
}
}
```
### Post-scan tag failure events
**Event pattern**:
```
{
"detail-type": "GuardDuty Malware Protection Post Scan Action Failed",
"source": "aws.guardduty"
}
```
**Sample notification schema for `ACCESS_DENIED`**:
```
{
"version": "0",
"id": "746acd83-d75c-5b84-91d2-dad5f13ba0d7",
"detail-type": "GuardDuty Malware Protection Post Scan Action Failed",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-06-10T16:16:08Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"eventTime": "2024-06-10T16:16:08Z",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "2024-03-10-16-16-00-7D723DE8DBE9Y2E0",
"eTag": "0e9eeec810ad8b61d69112c15c2a5hb6",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"postScanActions": [{
"actionType": "TAGGING",
"failureReason": "ACCESS_DENIED"
}]
}
}
```
**Sample notification schema for `MAX_TAG_LIMIT_EXCEEDED`**:
```
{
"version": "0",
"id": "746acd83-d75c-5b84-91d2-dad5f13ba0d7",
"detail-type": "GuardDuty Malware Protection Post Scan Action Failed",
"source": "aws.guardduty",
"account": "111122223333",
"time": "2024-06-10T16:16:08Z",
"region": "us-east-1",
"resources": ["arn:aws:guardduty:us-east-1:111122223333:malware-protection-plan/b4c7f464ab3a4EXAMPLE"],
"detail": {
"schemaVersion": "1.0",
"eventTime": "2024-06-10T16:16:08Z",
"s3ObjectDetails": {
"bucketName": "amzn-s3-demo-bucket",
"objectKey": "2024-03-10-16-16-00-7D723DE8DBE9Y2E0",
"eTag": "0e9eeec810ad8b61d69112c15c2a5hb6",
"versionId" : "d41d8cd98f00b204e9800998eEXAMPLE",
"s3Throttled": false
},
"postScanActions": [{
"actionType": "TAGGING",
"failureReason": "MAX_TAG_LIMIT_EXCEEDED"
}]
}
}
```
To troubleshoot these failure reasons, see [Troubleshooting S3 object post-scan tag failures](troubleshoot-s3-post-scan-tag-failures.md).
# Monitoring S3 object scans with GuardDuty managed tags
Use enable tagging option so that GuardDuty can add tags to your Amazon S3 object after completing the malware scan.
**Considerations for enabling tagging**
+ There is an associated usage cost when GuardDuty tags your S3 objects. For more information, see [Pricing and usage cost for Malware Protection for S3](pricing-malware-protection-for-s3-guardduty.md).
+ You must keep the required tagging permissions to your preferred IAM role associated with this bucket; otherwise, GuardDuty can't add tags to your scanned objects. The IAM role already includes the permissions to add tags to the scanned S3 objects. For more information, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md).
+ By default, you can associate up to 10 tags with an S3 object. For more information, see [Using tag-based access control (TBAC)](tag-based-access-s3-malware-protection.md).
After you enable tagging for an S3 bucket or specific prefixes, any newly uploaded object that gets scanned, will have an associated tag in the following key-value pair format:
`GuardDutyMalwareScanStatus`:`Scan-Result-Status`
For information about potential tag values, see [S3 object potential scan status and result status](monitoring-malware-protection-s3-scans-gdu.md#s3-object-scan-result-value-malware-protection).
# Troubleshooting S3 object post-scan tag failures in Malware Protection for S3
This section applies to you only if you [Enable tagging for scanned objects](enable-malware-protection-s3-bucket.md#tag-scanned-objects-s3-malware-protection) in your protected bucket.
When GuardDuty attempts to add a tag to your scanned S3 object, the action of tagging may result in a failure. The potential reasons why this may happen to your bucket are `ACCESS_DENIED` and `MAX_TAG_LIMIT_EXCEEDED`. Use the following topics to understand the potential reasons for these post-scan tag failure reasons and troubleshoot them.
**ACCESS\$1DENIED**
The following list provides potential reasons that may cause this issue:
+ The IAM role used for this protected S3 bucket is missing the **AllowPostScanTag** permission. Verify that the associated IAM role uses this bucket policy. For more information, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md).
+ The protected S3 bucket policy does't allow GuardDuty to add tags to this object.
+ The scanned S3 object no longer exists.
**MAX\$1TAG\$1LIMIT\$1EXCEEDED**
By default, you can associate up to 10 tags with an S3 object. For more information, see Considerations for GuardDuty to add a tag to your S3 object under [Enable tagging for scanned objects](enable-malware-protection-s3-bucket.md#tag-scanned-objects-s3-malware-protection).
# S3 object scan status metrics in CloudWatch
You can monitor GuardDuty using CloudWatch, which collects raw data and processes it into readable, near real-time metrics. These statistics are retained for 15 months, so that you can access historical information and gain a better perspective on how Malware Protection for S3 is performing. You can also set alarms that watch for certain thresholds, and send notifications or take actions when those thresholds are met. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
The CloudWatch metrics for Malware Protection for S3 are available at the resource level. You can query these metrics for each protected resource separately. The metrics are reported in the `AWS/GuardDuty/MalwareProtection` namespace. You can set up alarms on specific resources to monitor security posture.
|
|
| **Malware scan status metrics** |
| --- |
| **Metric** | **Description** |
| `CompletedScanCount` | The number of S3 object malware scans that completed in a given time frame. Valid Dimensions: `Malware Protection Plan Id` `Resource Name` Units: Count |
| `FailedScanCount` | The number of S3 object malware scans that failed in a given time frame. **Valid Dimensions**: `Malware Protection Plan Id` `Resource Name` Units: Count |
| `SkippedScanCount` | The number of S3 object malware scans that were skipped in a given time frame. **Valid Dimensions**: `Malware Protection Plan Id` `Resource Name` `Skipped Reason` Potential values `Unsupported` `MissingPermissions` Units: Count |
| **Malware scan result metrics** |
| --- |
| `InfectedScanCount` | The number of S3 object malware scans that detected potentially malicious object in a given time frame. Valid Dimensions: `Malware Protection Plan Id` `Resource Name` Units: Count |
| `CompletedScanBytes` | The number of S3 object bytes scanned in a given time frame. Valid Dimensions: `Malware Protection Plan Id` `Resource Name` Units: Count |
**Note**
By default, the statistics in the CloudWatch metrics are AVG.
The following dimensions are supported for the Malware Protection for S3 metrics.
|
|
| **Dimension** | **Description** |
| --- |--- |
| Malware Protection Plan Id | The unique identifier that is associated with the Malware Protection plan resource that GuardDuty creates for your protected resource. |
| Resource Name | The name of the protected resource. |
| Skipped Reason | The reason why an S3 object malware scan was skipped. Potential values `Unsupported` `MissingPermissions` |
For information about accessing and querying these metrics, see [Use Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) in the *Amazon CloudWatch User Guide*.
For information about setting up alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*.
# Troubleshooting
**Topics**
+ [Troubleshooting Malware Protection plan status](troubleshoot-s3-malware-protection-status-errors.md)
+ [Troubleshooting on-demand malware scan](troubleshoot-s3-malware-protection-on-demand.md)
# Troubleshooting Malware Protection plan status
For any protected bucket, GuardDuty displays the **Status** based on the ranking. For example, if a protected bucket has issues under both **Error** and **Warning** categories, GuardDuty will first display the issue that is associated with the **Error** status.
The following list includes the errors and the warning for the Malware Protection plan status.
**Errors**
+ [EventBridge notification is disabled for this S3 bucket](#eventbridge-notification-disabled-malware-protection-s3-error)
+ [EventBridge managed rule to receive S3 bucket events is missing](#eventbridge-managed-rule-missing-malware-protection-s3-error)
+ [S3 bucket no longer exists](#bucket-no-longer-exists-malware-protection-s3-error)
**Warning**
[Unable to put test object](#unable-put-test-object-malware-protection-s3-warning)
## EventBridge notification is disabled for this S3 bucket
The associated status reason code is `EVENTBRIDGE_MANAGED_EVENTS_DELIVERY_DISABLED`.
**Status detail**
GuardDuty uses EventBridge to receive a notification when a new object gets uploaded to this S3 bucket. This permission is missing in your IAM role.
**Steps to troubleshoot**
**Option 1: Add the following permission statement to your IAM role:**
```
{
"Sid": "AllowEnableS3EventBridgeEvents",
"Effect": "Allow",
"Action": [
"s3:PutBucketNotification",
"s3:GetBucketNotification"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket"
]
}
```
Replace *amzn-s3-demo-bucket* with your Amazon S3 bucket name.
**Option 2: Enable EventBridge notification by using the Amazon S3 console**
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. On the **Buckets** page, under **General purpose buckets** tab, select the bucket name associated with this error.
1. On this bucket page, choose the **Properties** tab.
1. Under the **Amazon EventBridge** section, select **Edit**.
1. On the **Edit Amazon EventBridge** page, for **Send notification to Amazon EventBridge for all events in this bucket**, select **On**.
1. Choose **Save changes**.
It may take a few minutes for the **Status** column value to change to **Active**.
## EventBridge managed rule to receive S3 bucket events is missing
The associated status reason code is `EVENTBRIDGE_MANAGED_RULE_DISABLED`.
**Status detail**
The EventBridge managed rule permissions to manage the EventBridge rule setup is missing.
**Steps to troubleshoot**
Add the following permission statement to your IAM role:
```
{
"Sid": "AllowManagedRuleToSendS3EventsToGuardDuty",
"Effect": "Allow",
"Action": [
"events:PutRule",
"events:DeleteRule",
"events:PutTargets",
"events:RemoveTargets"
],
"Resource": [
"arn:aws:events:*:*:rule/DO-NOT-DELETE-AmazonGuardDutyMalwareProtectionS3*"
],
"Condition": {
"StringEquals": {
"events:ManagedBy": "malware-protection-plan.guardduty.amazonaws.com"
}
}
}
```
It may take a few minutes for the **Status** column value to change to **Active**.
## S3 bucket no longer exists
The associated status reason code is `PROTECTED_RESOURCE_DELETED`.
**Status detail**
This S3 bucket was deleted from your account and it no longer exists.
**Step to troubleshoot**
If deleting the S3 bucket was not intentional, then you can create a new bucket by using the Amazon S3 console.
After creating the bucket successfully, enable Malware Protection for S3 by following the steps under the [Configuring Malware Protection for S3 for your bucket](configuring-malware-protection-for-s3-guardduty.md) page.
## Unable to put test object
The associated status reason code is `INSUFFICIENT_TEST_OBJECT_PERMISSIONS`.
**Note**
The permission to add a test object is optional. Missing this permission in your IAM role doesn't prevent Malware Protection for S3 to initiate malware scan on a newly uploaded object. After a scan initiates successfully, it may take a few minutes for the Malware Protection plan **Status** to change from **Warning** to **Active**.
If the IAM role includes this permission already, then this warning indicates a restrictive Amazon S3 bucket policy that does't allow the IAM access to put the test object in this S3 bucket.
**Status detail**
To validate the setup of the selected bucket, GuardDuty puts a test object in your bucket.
**Steps to troubleshoot**
You can choose to update the IAM role to include the missing permissions. To the selected IAM role, add the following permissions so that GuardDuty can put the test object to the selected resource:
```
{
"Sid": "AllowPutValidationObject",
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/malware-protection-resource-validation-object"
]
}
```
Replace *amzn-s3-demo-bucket* with your Amazon S3 bucket name. For information about IAM role permissions, see [Create or update IAM role policy](malware-protection-s3-iam-policy-prerequisite.md).
It may take a few minutes for the **Status** column value to change to **Active**.
# Troubleshooting on-demand malware scan
## Unable to start a scan.
Please ensure the scan request contains valid input and the Malware Protection Plan is enabled for the bucket.
# Editing Malware Protection plan for a protected bucket
You may need to edit the preferred IAM permissions policy, enable or disable tagging of the scanned S3 object, or add or remove S3 object prefixes. For example, when you enabled Malware Protection for S3 for your bucket, you decided to not enable tagging the scanned S3 object with the scan result. However, now you want GuardDuty to add the predefined tag and the scan result as the tag value.
Choose a preferred access method to update the Malware Protection plan for your protected S3 bucket.
------
#### [ Console ]
**To edit a Malware Protection plan**
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. In the navigation pane, choose **Malware Protection for S3**.
1. Under **Protected buckets**, select the bucket for which you want to edit the existing configuration.
1. Choose **Edit**.
1. Update the existing configuration and settings for your bucket and confirm the changes. For information about description and steps for each section, see [Enabling Malware Protection for S3 for your bucket](enable-malware-protection-s3-bucket.md).
Monitor the **Status** column for this protected bucket. If it appears as either **Warning** or **Error**, see [Troubleshooting Malware Protection plan status](troubleshoot-s3-malware-protection-status-errors.md).
------
#### [ API/CLI ]
**To edit Malware Protection plan by using API or AWS CLI**
+ **By using API**
Run the [UpdateMalwareProtectionPlan](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_UpdateMalwareProtectionPlan.html) API by using the Malware Protection plan ID associated with this plan resource.
To retrieve the Malware Protection plan ID in a specific Region, you can run the [ListMalwareProtectionPlans](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListMalwareProtectionPlans.html) API in that Region.
+ **By using AWS CLI**
The following list provides AWS CLI example commands to update the Malware Protection plan resource. You will need the Malware Protection plan ID associated with your S3 bucket.
**AWS CLI example commands**
+ Use the following AWS CLI command to **enable or disable** tagging for the Malware Protection plan resource associated with your S3 bucket:
```
aws guardduty update-malware-protection-plan --malware-protection-plan-id 4cc8bf26c4d75EXAMPLE --actions "Tagging"={"Status"="ENABLED|DISABLED"}
```
+ Use the following AWS CLI command to **add an object prefix** to the Malware Protection plan resource associated with your S3 bucket:
```
aws guardduty update-malware-protection-plan --malware-protection-plan-id 4cc8bf26c4d75EXAMPLE --protected-resource "S3Bucket"={"ObjectPrefixes"=["amzn-s3-demo-1", "amzn-s3-demo-2"]}
```
Make sure to include the existing object prefixes in this command; otherwise, GuardDuty will remove those prefixes when editing the Malware Protection plan resource.
+ Use the following AWS CLI command to **remove an object prefix** from the Malware Protection plan resource associated with your S3 bucket:
```
aws guardduty update-malware-protection-plan --malware-protection-plan-id 4cc8bf26c4d75EXAMPLE --protected-resource "S3Bucket"={"ObjectPrefixes"=[""]}
```
If you don't already have the Malware Protection plan ID for this resource, you can run the following AWS CLI command and replace *us-east-1* with the Region for which you want to list the Malware Protection plan IDs.
```
aws guardduty list-malware-protection-plans --region us-east-1
```
------
# Disabling Malware Protection for S3 for a protected bucket
When you disable Malware Protection for S3 for a protected bucket, GuardDuty deletes the Malware Protection plan ID associated with that bucket. GuardDuty will no longer start a malware scan when a new object gets uploaded to this bucket or one of the selected object prefixes.
If you have enabled GuardDuty and now want to suspend or disable GuardDuty, see [Suspending or disabling GuardDuty](guardduty_suspend-disable.md). Because there is no concept of detector ID in Malware Protection for S3, disabling or suspending GuardDuty **doesn't** impact the status of a protected bucket in your account. You can continue using Malware Protection for S3 feature independently with the associated standard pricing. For more information, see [Reviewing usage cost for Malware Protection for S3Reviewing usage cost](usage-cost-malware-protection-s3-gdu.md). To stop using Malware Protection for S3, you will need to disable it for all the protected buckets in your account. If you want to continue using GuardDuty and disable only Malware Protection for S3 for a bucket, the following steps are not going to impact the configuration of the GuardDuty service and other protection plans that you may have enabled.
Choose a preferred access method to disable Malware Protection for S3 in your protected S3 bucket.
------
#### [ Console ]
**To disable Malware Protection for S3 by using GuardDuty console**
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. In the navigation pane, choose **Malware Protection for S3**.
1. Under **Protected buckets**, select the bucket for which you want to disable Malware Protection for S3.
You can select only one protected bucket at a time. To disable Malware Protection for S3 for more than one bucket, follow these steps again for another S3 bucket.
1. Choose **Disable** to confirm the selection.
------
#### [ API/CLI ]
**To disable Malware Protection for S3 by using API or AWS CLI**
+ **By using API**
Run the [DeleteMalwareProtectionPlan](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_DeleteMalwareProtectionPlan.html) API by using the Malware Protection plan ID associated with this plan resource.
To retrieve the Malware Protection plan ID, you can run the [ListMalwareProtectionPlans](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListMalwareProtectionPlans.html) API.
+ **By using AWS CLI**
Alternatively, you can run the following AWS CLI command to disable Malware Protection for S3 by replacing *4cc8bf26c4d75EXAMPLE* with the Malware Protection plan ID associated to this S3 bucket:
```
aws guardduty delete-malware-protection-plan --malware-protection-plan-id 4cc8bf26c4d75EXAMPLE
```
If you don't already have the Malware Protection plan ID for this S3 bucket, you can run the following AWS CLI command and replace *us-east-1* with the Region for which you want to list the Malware Protection plan IDs.
```
aws guardduty list-malware-protection-plans --region us-east-1
```
------
# Supportability of Amazon S3 features
The following table specifies whether or not Malware Protection for S3 supports the listed Amazon S3 features.
| S3 feature name | Is the support available? | Description |
| --- | --- | --- |
| S3 Storage Class - S3 Standard S3 Storage Class - S3 Standard-Infrequent Access S3 Storage Class - S3 One Zone-Infrequent Access S3 Storage Class - S3 Glacier Instant Retrieval | Yes | S3 objects can be retrieved without restoring asynchronously. |
| S3 Storage Class - S3 Intelligent-Tiering | Conditional | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/guardduty/latest/ug/supported-s3-features-malware-protection-s3.html) |
| S3 Storage Class - S3 Express One Zone (Directory bucket) | No | GuardDuty supports only general purpose buckets for Malware Protection for S3. |
| S3 Storage Class - S3 Glacier Flexible Retrieval S3 Storage Class - S3 Glacier Deep Archive | No | The S3 objects must be restored before they can be accessed. |
| Amazon S3 on Outposts | No | Malware Protection for S3 is not supported on Outposts. |
| S3 versioning | Yes | All the uploaded S3 objects are scanned for malware. If you uploaded an object with file version v1 and immediately uploaded another version override with v2, then GuardDuty will scan both the object file versions v1 and v2. However, the scan start time might not be in the same order. |
| S3 Replication - scan replicated object | Yes | If the destination bucket is a protected resource, then GuardDuty will scan all the S3 objects are replicated to the prefixes that are protected and monitored. |
| S3 Replication: Replicate on scan result tag | No | You can't define a replication rule based on the scan result tag. Amazon S3 does't support replication for tag, except for on create. |
| Data Encryption - S3-SSE Data Encryption - SSE-KMS Data Encryption - DSSE-KMS AWS KMS - Customer managed key | Yes | GuardDuty supports malware scans for S3 objects that are encrypted with managed and customer managed keys. Ensure that the IAM role includes the permission to use the key. For more information, see [Adding IAM policy permissions](malware-protection-s3-iam-policy-prerequisite.md#attach-iam-policy-s3-malware-protection). |
| Data Encryption - SSE-C | No | Malware Protection for S3 doesn't support scanning S3 objects that are encrypted with keys that are not accessible. |
| Client side encryption | No | When your Amazon S3 objects are encrypted by using Amazon S3 Encryption Client, your objects aren't exposed to any third party, including AWS. For information on why this is not supported, see [Protecting data by using client-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingClientSideEncryption.html). CSE-KMS encrypted objects are received as an encrypted blob where the encryption can't be determined. Therefore, GuardDuty processes them as they are received, and scans the encrypted blob as a regular file. GuardDuty doesn't return an `UNSUPPORTED` scan status for such objects, unless any of the [Quotas in Malware Protection for S3](malware-protection-s3-quotas-guardduty.md) exceeds. |
| S3 object lock and legal hold | Yes | Locked S3 objects are locked based on WORM - Write Once Read Many. Malware Protection for S3 can access and scan the objects. |
| Requester pays | Yes | Malware Protection for S3 can scan the buckets that are set up with *Requester Pays*. The requester will pay for the S3 calls. For more information, see [Using Requester Pays buckets for storage transfers and usage](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) in the *Amazon S3 User Guide*. |
| S3: Storage lifecycle | Yes | You can define lifecycle policies based on the scan result tag. For example, auto-delete malicious objects. For more information about lifcycle configuration, see [Managing your storage lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) in the *Amazon S3 User Guide*. |
| S3: Tag-based access control (TBAC) | Yes | You can define bucket resource policies based on your S3 object scan result tag. For example, prevent access to S3 objects that are not yet scanned, or GuardDuty detected threats. For more information, see [Using tag-based access control (TBAC) with Malware Protection for S3](tag-based-access-s3-malware-protection.md). |
# Quotas in Malware Protection for S3
This section provides default quotas, often referred to as limits. Unless specified, each quota is Region-specific. To view default quotas specific to using the foundational GuardDuty service, see [Amazon GuardDuty quotas](guardduty_limits.md).
The following tables describe the multiple quotas that will apply to your AWS account.
| Quota name | AWS default quota value | Is it adjustable? | Description |
| --- | --- | --- | --- |
| Maximum S3 object size | 100 GB | No | The maximum S3 object size that GuardDuty will attempt to scan for malware. Although this quota is not adjustable, if you need to scan larger objects, contact AWS Support to determine if GuardDuty can increase the quota for your use case. |
| Extracted archive bytes | 100 GB | No | The maximum amount of data that GuardDuty can extract and analyze from an archive file. GuardDuty will skip archive files extracting to more than 100 GB. Files with an extremely high compression ratio between the compressed archive size and the extracted content size may be subject to limits even if the extracted content size is below this quota. |
| Extracted archive files | 10,000 | No | The maximum number of files that GuardDuty can extract and analyze in an archive file. If the archive contains more than 10,000 files, then GuardDuty will have to skip the archived file. Compound files types are potentially subject to these limits. The file types include, but are not limited to, Multipurpose Internet Mail Extensions (MIME) encoded email messages, Compiled Python (PYC) files, Compiled HTML Help (CHM) files, all installers, and OpenDocument Format (ODF) documents. |
| Maximum archive depth levels | 5 | No | The maximum levels of nested archives that GuardDuty can extract. If the archive includes files that are nested beyond this value, then GuardDuty will skip those nested files. |
| Maximum protected buckets | 25 | No | The maximum number of S3 buckets for which you can enable Malware Protection for S3. This quota limit is per account in each Region. |