Customizations in Malware Protection - Amazon GuardDuty
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).

Customizations in Malware Protection

This section describes how you can customize the scanning options for your Amazon EC2 instances or container workloads when a malware scan gets invoked, either initiated on-demand or through GuardDuty.

General settings

Snapshots retention

GuardDuty provides you with the option to retain the snapshots of your EBS volumes in your Amazon account. By default, the snapshots retention setting is turned off. The snapshots will only be retained if you have this setting turned on before the scan initiates.

As the scan initiates, GuardDuty generates the replica EBS volumes based on the snapshots of your EBS volumes. After the scan completes and the snapshots retention setting in your account was turned on already, the snapshots of your EBS volumes will be retained only when malware is found and Malware Protection finding types get generated. Whether or not you have turned on the snapshots retention setting, when no malware is detected, GuardDuty automatically deletes the snapshots of your EBS volumes.

Snapshots usage cost

During the malware scanning, as GuardDuty creates the snapshots of your Amazon EBS volumes, there is a usage cost associated with this step. If you turn on the snapshots retention setting for your account, when malware is found and the snapshots get retained, you will incur usage cost for the same. For information on cost of snapshots and their retention, see Amazon EBS pricing.

Choose your preferred access method to turn on the snapshots retention setting.

Console
  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, under Protection plans, choose Malware Protection.

  3. Choose General settings in the bottom section of the console. To retain the snapshots, turn on Snapshots retention.

API/CLI
  1. Run UpdateMalwareScanSettings to update the current configuration for snapshot retention setting.

  2. Alternatively, you can run the following Amazon CLI command to automatically retain snapshots when GuardDuty Malware Protection generates findings.

    Ensure to replace the detector-id with your own valid detectorId.

  3. You can find your own detectorId for your current Region on the Settings page in the https://console.amazonaws.cn/guardduty/ console.

    aws guardduty update-malware-scan-settings --detector-id 60b8777933648562554d637e0e4bb3b2 --ebs-snapshot-preservation "RETENTION_WITH_FINDING"
  4. If you want to turn off snapshots retention, replace RETENTION_WITH_FINDING with NO_RETENTION.

Scan options with user-defined tags

By using GuardDuty-initiated malware scan, you can also specify tags to either include or exclude Amazon EC2 instances and Amazon EBS volumes from the scanning and threat detection process. You can customize each GuardDuty-initiated malware scan by editing tags in either the inclusion or exclusion tags list. Each list can include up to 50 tags.

If you don't already have user-defined tags associated to your EC2 resources, see Tag your Amazon EC2 resources in the Amazon EC2 User Guide for Linux Instances or Tag your Amazon EC2 resources in the Amazon EC2 User Guide for Windows Instances.

Note

On-demand malware scan doesn't support scan options with user-defined tags. It supports Global GuardDutyExcluded tag.

To exclude EC2 instances from malware scan

If you want to exclude any Amazon EC2 instance or Amazon EBS volume during the scanning process, you can set the GuardDutyExcluded tag to true for any Amazon EC2 instance or Amazon EBS volume, and GuardDuty won't scan it. For more information about GuardDutyExcluded tag, see Service-linked role permissions for Malware Protection. You can also add an Amazon EC2 instance tag to an exclusion list. If you add multiple tags to the exclusion tags list, any Amazon EC2 instance that contains at least one of these tags will be excluded from the malware scanning process.

Choose your preferred access method to add a tag associated with an Amazon EC2 instance, to an exclusion list.

Console
  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, under Protection plans, choose Malware Protection.

  3. Expand Inclusion/Exclusion tags section. Choose Add tags.

  4. Choose Exclusion tags and then choose to Confirm.

  5. Specify the tag's Key and Value pair that you want to exclude. It is optional to provide the Value. After you add all the tags, choose Save.

    Important

    Tag keys and values are case-sensitive. For more information, see Tag restrictions in the Amazon EC2 User Guide for Linux Instances or Tag restrictions in the Amazon EC2 User Guide for Windows Instances.

    If a value for a key is not provided and the EC2 instance is tagged with the specified key, this EC2 instance will be excluded from the GuardDuty-initiated malware scan scanning process, regardless of the tag's assigned value.

API/CLI
  • Update the malware scan settings by excluding an EC2 instance or a container workload from the scanning process.

    The following Amazon CLI example command adds a new tag to the exclusion tags list. Ensure to replace the example detector-id with your own valid detectorId.

    MapEquals is a list of Key/Value pairs.

    You can find your own detectorId for your current Region on the Settings page in the https://console.amazonaws.cn/guardduty/ console.

    aws guardduty update-malware-scan-settings --detector-id 60b8777933648562554d637e0e4bb3b2 --scan-resource-criteria '{"Exclude": {"EC2_INSTANCE_TAG" : {"MapEquals": [{ "Key": "TestKeyWithValue", "Value": "TestValue" }, {"Key":"TestKeyWithoutValue"} ]}}}' --ebs-snapshot-preservation "RETENTION_WITH_FINDING"
    Important

    Tag keys and values are case-sensitive. For more information, see Tag restrictions in the Amazon EC2 User Guide for Linux Instances or Tag restrictions in the Amazon EC2 User Guide for Windows Instances.

To include EC2 instances in malware scan

If you want to scan an EC2 instance, add its tag to the inclusion list. When you add a tag to an inclusion tags list, an EC2 instance that doesn't contain any of the added tags is skipped from the malware scan. If you add multiple tags to the inclusion tags list, an EC2 instance that contains at least one of those tags is included in the malware scan. Sometimes, an EC2 instance may be skipped during the scanning process. For more information, see Reasons for skipping resource during malware scan.

Choose your preferred access method to add a tag associated with an EC2 instance, to an inclusion list.

Console
  1. Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.

  2. In the navigation pane, under Protection plans, choose Malware Protection.

  3. Expand Inclusion/Exclusion tags section. Choose Add tags.

  4. Choose Inclusion tags and then choose Confirm.

  5. Choose Add new inclusion tag and specify the tag's Key and Value pair that you want to include. It is optional to provide the Value.

    After you have added all the inclusion tags, choose Save.

    If a value for a key is not provided an EC2 instance is tagged with the specified key, the EC2 instance will be included in the Malware Protection scanning process, regardless of the tag's assigned value.

API/CLI
  • Update the malware scan settings to include an EC2 instance or a container workload in the scanning process.

    The following Amazon CLI example command adds a new tag to the inclusion tags list. Ensure that you replace the example detector-id with your own valid detectorId. Replace the example TestKey and TestValue with the Key and Value pair of the tag associated with your EC2 resource.

    MapEquals is a list of Key/Value pairs.

    You can find your own detectorId for your current Region on the Settings page in the https://console.amazonaws.cn/guardduty/ console.

    aws guardduty update-malware-scan-settings --detector-id 60b8777933648562554d637e0e4bb3b2 --scan-resource-criteria '{"Include": {"EC2_INSTANCE_TAG" : {"MapEquals": [{ "Key": "TestKeyWithValue", "Value": "TestValue" }, {"Key":"TestKeyWithoutValue"} ]}}}' --ebs-snapshot-preservation "RETENTION_WITH_FINDING"
    Important

    Tag keys and values are case-sensitive. For more information, see Tag restrictions in the Amazon EC2 User Guide for Linux Instances or Tag restrictions in the Amazon EC2 User Guide for Windows Instances.

Note

It may take up to 5 minutes for GuardDuty to detect a new tag.

At any time, you can either choose Inclusion tags or Exclusion tags but not both. If you want to switch between the tags, choose that tag from the dropdown menu when you add new tags, and Confirm your selection. This action clears all your current tags.

Global GuardDutyExcluded tag

By default, the snapshots of your EBS volumes get created with a GuardDutyScanId tag. Do not remove this tag because doing so will prevent GuardDuty from accessing the snapshots. Both scan types in Malware Protection do not scan the Amazon EC2 instances or Amazon EBS volumes that have the GuardDutyExcluded tag set to true. If a Malware Protection scan on such a resource, a scan ID will be generated but the scan will be skipped with an EXCLUDED_BY_SCAN_SETTINGS reason. For more information, see Reasons for skipping resource during malware scan.