How does Malware Protection for S3 work? - Amazon GuardDuty
OverviewIAM PassRole permissionsOptional tagging of objects based on scan resultAfter enabling Malware Protection for S3 for a bucketCapabilities of Malware Protection for S3
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

How does Malware Protection for S3 work?

This section describes components of Malware Protection for S3 that will help you understand how it works.

Overview

You can enable Malware Protection for S3 for an Amazon S3 bucket that belongs to your own Amazon Web Services 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 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 PassRole permissions

Malware Protection for S3 uses an IAM PassRole 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 Prerequisite - Create or update IAM PassRole policy.

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 PassRole 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 result value.

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.

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 for Malware Protection for S3.

After enabling 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 to 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*.

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 by using an Amazon PrivateLink and then reads, decrypts, and scan it in an isolated environment in the same Region. For the duration of the scan, GuardDuty temporarily stores the downloaded S3 object within the scanning environment. After the malware scan completes, GuardDuty deletes the downloaded copy of the object.

View S3 object scan 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.

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, the generated finding gets exported to an S3 bucket and EventBridge event bus.

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.

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.

  • Enable through console, by using API/Amazon CLI, or Amazon CloudFormation – Choose a preferred method to enable Malware Protection for S3.

    You can enable Malware Protection for S3 using Infrastructure as code (IaC) platform such as Terraform. For more information, see Resource: aws_guardduty_malware_protection_plan.

  • Supports tagging scanned S3 object (optional) – After each malware scan, GuardDuty will add a tag that indicates the scan status of the uploaded S3 object. 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 found to be malicious and have the tag value as THREATS_FOUND.

  • Amazon EventBridge notifications – When you set up an EventBridge rule, you will receive notification about the S3 malware scan status.

    Your delegated GuardDuty administrator account will receive an EventBridge notification when a member account enables this protection for an Amazon S3 bucket that belongs to their own account.

  • CloudWatch metrics – View metrics embedded in GuardDuty console. These metrics include details about your S3 objects.

When you also enable GuardDuty, you will receive a security finding when an S3 object is identified as containing a potentially malicious file. GuardDuty recommends steps to help you remediate the generated finding.