GuardDuty Malware Protection for Backup: IAM Role Permissions - Amazon GuardDuty
Customer role provided for malware scanningDetails about the permissionsSecuring the RoleHow GuardDuty Malware Protection uses grants in Amazon KMSGuardDuty Malware Protection Encryption ContextPermissions and trust policy for the role
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).

GuardDuty Malware Protection for Backup: IAM Role Permissions

Customer role provided for malware scanning

GuardDuty Malware Protection expects a customer role (scanner role) to be provided when scans are initiated on Backup resources, namely snapshots, AMIs and EBS/EC2/S3 Recovery Points. This role provides the permissions required by GuardDuty to perform the scan on those specific resources. The permissions policy and the trust policy for this role can be found in Permissions and trust policy for the role. The section below describes why each of these permissions are required.

Details about the permissions

  • ModifySnapshotAttribute - Allows unencrypted and customer managed key encrypted snapshots to be accessed by GuardDuty Malware Protection service account.

  • CreateGrant - Allows GuardDuty Malware Protection to create and access a Customer Managed Key encrypted EBS volume from the customer managed key encrypted snapshot that the GuardDuty service account is provided access to.

  • RetireGrant - Allows GuardDuty Malware Protection to retire the grants that were created on the Customer Managed Key for reading encrypted snapshots

  • ReEncryptTo and ReEncryptFrom - Required by EBS to give GuardDuty access to snapshots that are encrypted with customer managed keys and create encrypted volumes from them. Although customers might consider ReEncryption of a snapshot during sharing as key transition, snapshots remain immutable from the customer perspective once created.

  • ListSnapshotBlocks and GetSnapshotBlock - EBS Direct APIs are used to access the snapshot blocks for an Amazon Managed Key encrypted snapshot. This is done because Amazon Managed Key encrypted snapshots cannot otherwise be accessed cross-account.

  • Decrypt - Allows decrypting base snapshots that are customer managed key encrypted when they are downloaded into memory using EBS Direct APIs as part of incremental scanning.

  • ListChangedBlocks - EBS Direct API used in incremental snapshot scanning to get the list of changed blocks between two snapshots.

  • DescribeKey - Allows GuardDuty Malware Protection to determine the keyId of the Amazon managed key in the customer account.

  • DescribeImages - Allows an AMI to be described to obtain the list of snapshots belonging to the AMI.

  • DescribeRecoveryPoint - Allows the service to fetch the Recovery Point details and verify the resource type for the Recovery Point.

  • CreateBackupAccessPoint, DescribeBackupAccessPoint, DeleteBackupAccessPoint - Allows the service to create, describe, and delete the Access Point that is required for accessing Recovery Points.

  • kms:Decrypt - Allows the service to access objects in a S3 Recovery Point during a S3 Recovery Point scan.

Securing the Role

The role must be configured with a trust policy that trusts the GuardDuty Malware Protection service principal. This ensures that no principal other than the GuardDuty service can assume this role. Further, you are encouraged to scope down the policies to specific resources instead of *. This includes snapshot ids and key ids. Doing this will ensure that the role provides access only to those specific resources.

Important

Incorrect configuration could result in scan failures due to insufficient permissions.

How GuardDuty Malware Protection uses grants in Amazon KMS

GuardDuty Malware Protection requires grants to use your KMS keys.

When you start a scan on an encrypted snapshot or an EC2 AMI consisting of encrypted snapshots, GuardDuty Malware Protection creates grants on your behalf by sending a CreateGrant request to Amazon KMS. These grants give GuardDuty access to a specific key in your account.

GuardDuty Malware Protection requires the grant to use your customer managed key for the following internal operations:

  • Send DescribeKey requests to Amazon to fetch details about the symmetric customer managed key that the resource submitted for a malware scan is encrypted with.

  • Create an EBS volume from an encrypted snapshot using the CreateVolume API and encrypt the volume with the same key.

  • Access snapshot blocks on the snapshot through the GetSnapshotBlock API during an incremental scan.

  • Send Decrypt requests to Amazon KMS to decrypt the encrypted data keys so that they can be used to read the data on the snapshot during the scan.

You can revoke the created grant, or remove the service's access to the customer managed key at any time. If you do, GuardDuty won't be able to access any of the data encrypted by the customer managed key, which affects operations that are dependent on that data.

GuardDuty Malware Protection Encryption Context

An encryption context is an optional set of key-value pairs that contain additional contextual information about the data.

When you include an encryption context in a request to encrypt data, Amazon KMS; binds the encryption context to the encrypted data. To decrypt data, you include the same encryption context in the request.

GuardDuty Malware Protection uses one of the two encryption contexts.

Encryption Context 1: Key is aws:guardduty:id.

"encryptionContext": {
    "aws:guardduty:id": "snap-11112222333344"
}

This encryption context is used with grant operations: CreateGrant, Decrypt, GenerateDataKeyWithoutPlaintext, ReEncryptTo, RetireGrant, DescribeKey.

One grant is created on the current resource with this encryption context and grant operations.

Encryption Context 2: Key is aws:ebs:id

"encryptionContext": {
    "aws:ebs:id": "snap-11112222333344"
}

This encryption context is used with grant operations: ReEncryptFrom, Decrypt, RetireGrant, DescribeKey.

Three grants are created with these encryption contexts and grant operations. One on the target snapshot with the ReEncryptFrom grant operation. A second one on the target snapshot with Decrypt, RetireGrant, DescribeKey operations. And a third one on the base snapshot with the same grant operations as the second grant.

Permissions and trust policy for the role

Permissions Policy

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [{
            "Effect": "Allow",
            "Action": [
                "ebs:ListSnapshotBlocks",
                "ebs:ListChangedBlocks",
                "ebs:GetSnapshotBlock"
            ],
            "Resource": "arn:aws:ec2:*::snapshot/*"
        },
        {
            "Sid": "CreateGrantPermissions",
            "Effect": "Allow",
            "Action": "kms:CreateGrant",
            "Resource": "arn:aws:kms:*:*:key/*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "kms:EncryptionContext:aws:guardduty:id": "snap-*",
                    "kms:ViaService": [
                        "guardduty.*.amazonaws.com",
                        "backup.*.amazonaws.com"
                    ]
                },
                "ForAllValues:StringEquals": {
                    "kms:GrantOperations": [
                        "Decrypt",
                        "CreateGrant",
                        "GenerateDataKeyWithoutPlaintext",
                        "ReEncryptFrom",
                        "ReEncryptTo",
                        "RetireGrant",
                        "DescribeKey"
                    ]
                },
                "Bool": {
                    "kms:GrantIsForAWSResource": "true"
                }
            }
        },
        {
            "Sid": "CreateGrantPermissionsForReEncryptAndDirectAPIs",
            "Effect": "Allow",
            "Action": "kms:CreateGrant",
            "Resource": "arn:aws:kms:*:*:key/*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "kms:EncryptionContext:aws:ebs:id": "snap-*",
                    "kms:ViaService": [
                        "guardduty.*.amazonaws.com",
                        "backup.*.amazonaws.com"
                    ]
                },
                "ForAllValues:StringEquals": {
                    "kms:GrantOperations": [
                        "Decrypt",
                        "ReEncryptTo",
                        "ReEncryptFrom",
                        "RetireGrant",
                        "DescribeKey"
                    ]
                },
                "Bool": {
                    "kms:GrantIsForAWSResource": "true"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeImages",
                "ec2:DescribeSnapshots"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ShareSnapshotPermission",
            "Effect": "Allow",
            "Action": [
                "ec2:ModifySnapshotAttribute"
            ],
            "Resource": "arn:aws:ec2:*:*:snapshot/*"
        },
        {
            "Sid": "ShareSnapshotKMSPermission",
            "Effect": "Allow",
            "Action": [
                "kms:ReEncryptTo",
                "kms:ReEncryptFrom"
            ],
            "Resource": "arn:aws:kms:*:*:key/*",
            "Condition": {
                "StringLike": {
                    "kms:ViaService": "ec2.*.amazonaws.com"
                }
            }
        },
        {
            "Sid": "DescribeKeyPermission",
            "Effect": "Allow",
            "Action": "kms:DescribeKey",
            "Resource": "arn:aws:kms:*:*:key/*"
        },
        {
            "Sid": "DescribeRecoveryPointPermission",
            "Effect": "Allow",
            "Action": [
                "backup:DescribeRecoveryPoint"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CreateBackupAccessPointPermissions",
            "Effect" : "Allow",
            "Action" : [
                "backup:CreateBackupAccessPoint"  
            ],
            "Resource": "arn:aws:backup:*:*:recovery-point:*"
        },
        {
            "Sid": "ReadAndDeleteBackupAccessPointPermissions",
            "Effect" : "Allow",
            "Action" : [
                "backup:DescribeBackupAccessPoint",
                "backup:DeleteBackupAccessPoint"     
            ],
            "Resource": "*"
        },
        {
            "Sid": "KMSKeyPermissionsForInstantAccess",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:*:*:key/*",
            "Condition": {
                "StringLike": {
                    "kms:ViaService": "backup.*.amazonaws.com"
                }
            }
        }
    ]
}

Trust Policy

{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "malware-protection.guardduty.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}