Configuration options for retrieving sensitive data samples with Macie

You can optionally configure and use Amazon Macie to retrieve and reveal samples of sensitive data that Macie reports in individual findings. If you retrieve and reveal sensitive data samples for a finding, Macie uses data in the corresponding sensitive data discovery result to locate occurrences of sensitive data in the affected Amazon Simple Storage Service (Amazon S3) object. Macie then extracts samples of those occurrences from the affected object. Macie encrypts the extracted data with an AWS Key Management Service (AWS KMS) key that you specify, temporarily stores the encrypted data in a cache, and returns the data in your results for the finding. Soon after extraction and encryption, Macie permanently deletes the data from the cache unless additional retention is temporarily required to resolve an operational issue.

Macie doesn't use the Macie service-linked role for your account to locate, retrieve, encrypt, or reveal sensitive data samples for affected S3 objects. Instead, Macie uses settings and resources that you configure for your account. When you configure the settings in Macie, you specify how to access affected S3 objects. You also specify which AWS KMS key to use to encrypt the samples. You can configure the settings in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) and Israel (Tel Aviv) Regions.

To access affected S3 objects and retrieve sensitive data samples from them, you have two options. You can configure Macie to use AWS Identity and Access Management (IAM) user credentials or assume an IAM role:

You can use either configuration with any type of Macie account—the delegated Macie administrator account for an organization, a Macie member account in an organization, or a standalone Macie account.

The following topics explain options, requirements, and considerations that can help you determine how to configure the settings and resources for your account. This includes the trust and permissions policies to attach to an IAM role. For additional recommendations and examples of policies that you might use to retrieve and reveal sensitive data samples, see the following blog post on the AWS Security Blog: How to use Amazon Macie to preview sensitive data in S3 buckets.

Determining which access method to use

When determining which configuration is best for your AWS environment, a key consideration is whether your environment includes multiple Amazon Macie accounts that are centrally managed as an organization. If you’re the delegated Macie administrator for an organization, configuring Macie to assume an IAM role can streamline retrieval of sensitive data samples from affected S3 objects for accounts in your organization. With this approach, you create an IAM role in your administrator account. You also create an IAM role in each applicable member account. The role in your administrator account delegates access to Macie. The role in a member account delegates cross-account access to the role in your administrator account. If implemented, you can then use role chaining to access affected S3 objects for your member accounts.

Also consider who has direct access to individual findings by default. To retrieve and reveal sensitive data samples for a finding, a user must first have access to the finding:

If you plan to access affected S3 objects by using an IAM role, also consider the following:

Subsequent topics in this section provide additional details and considerations for each type of configuration. For IAM roles, this includes the trust and permissions policies to attach to a role. If you’re not sure which type of configuration is best for your environment, ask your AWS administrator for assistance.

Using IAM user credentials to access affected S3 objects

If you configure Amazon Macie to retrieve sensitive data samples by using IAM user credentials, each user of your Macie account uses their IAM identity to locate, retrieve, encrypt, and reveal samples for individual findings. This means that a user can retrieve and reveal sensitive data samples for a finding if their IAM identity is allowed to access the requisite resources and data, and perform the requisite actions. All the requisite actions are logged in AWS CloudTrail.

To retrieve and reveal sensitive data samples for a particular finding, a user must be allowed to access the following data and resources: the finding, the corresponding sensitive data discovery result, the affected S3 bucket, and the affected S3 object. They must also be allowed to use the AWS KMS key that was used to encrypt the affected object, if applicable, and the AWS KMS key that you configure Macie to use to encrypt sensitive data samples. If any IAM policies, resource policies, or other permissions settings deny the requisite access, the user won’t be able to retrieve and reveal samples for the finding.

To set up this type of configuration, complete the following general tasks:

For information about performing these tasks, see Configuring Macie to retrieve sensitive data samples.

Assuming an IAM role to access affected S3 objects

To configure Amazon Macie to retrieve sensitive data samples by assuming an IAM role, start by creating an IAM role that delegates access to Amazon Macie. Ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. When a user of your Macie account then chooses to retrieve and reveal sensitive data samples for a finding, Macie assumes the role to retrieve the samples from the affected S3 object. Macie assumes the role only when a user chooses to retrieve and reveal samples for a finding. To assume the role, Macie uses the AssumeRole operation of the AWS Security Token Service (AWS STS) API. All the requisite actions are logged in AWS CloudTrail.

To retrieve and reveal sensitive data samples for a particular finding, a user must be allowed to access the finding, the corresponding sensitive data discovery result, and the AWS KMS key that you configure Macie to use to encrypt sensitive data samples. The IAM role must allow Macie to access the affected S3 bucket and the affected S3 object. The role must also be allowed to use the AWS KMS key that was used to encrypt the affected object, if applicable. If any IAM policies, resource policies, or other permissions settings deny the requisite access, the user won’t be able to retrieve and reveal samples for the finding.

To set up this type of configuration, complete the following general tasks. If you have a member account in an organization, work with your Macie administrator to determine whether and how to configure the settings and resources for your account.

For information about performing these tasks, see Configuring Macie to retrieve sensitive data samples.

Configuring an IAM role to access affected S3 objects

To access affected S3 objects by using an IAM role, start by creating and configuring a role that delegates access to Amazon Macie. Ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. How you do this depends on the type of Macie account that you have.

The following sections provide details about the trust and permissions policies to attach to the IAM role for each type of Macie account. Choose the section for the type of account that you have.

For detailed information about using IAM to create the role, see Creating a role using custom trust policies in the AWS Identity and Access Management User Guide.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RetrieveS3Objects",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AssumeMacieRevealRoleForCrossAccountAccess",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": "arn:aws:iam::*:role/IAMRoleName"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowMacieReveal",
            "Effect": "Allow",
            "Principal": {
                "Service": "reveal-samples.macie.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "accountID"
                }
            }
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RetrieveS3Objects",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowMacieAdminRevealRoleForCrossAccountAccess",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::administratorAccountID:role/IAMRoleName"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "externalID",
                    "aws:PrincipalOrgID": "${aws:ResourceOrgID}"
                }
            }
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RetrieveS3Objects",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowMacieReveal",
            "Effect": "Allow",
            "Principal": {
                "Service": "reveal-samples.macie.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "accountID"
                }
            }
        }
    ]
}

Decrypting affected S3 objects

Amazon S3 supports multiple encryption options for S3 objects. For most of these options, no additional resources or permissions are required for an IAM user or role to decrypt and retrieve sensitive data samples from an affected object. This is the case for an object that's encrypted using server-side encryption with an Amazon S3 managed key or an AWS managed AWS KMS key.

However, if an S3 object is encrypted with a customer managed AWS KMS key, additional permissions are required to decrypt and retrieve sensitive data samples from the object. More specifically, the key policy for the KMS key must allow the IAM user or role to perform the kms:Decrypt action. Otherwise, an error occurs and Amazon Macie doesn't retrieve any samples from the object. To learn how to provide this access for an IAM user, see KMS key access and permissions in the AWS Key Management Service Developer Guide.

How to provide this access for an IAM role depends on whether the account that owns the AWS KMS key also owns the role:

This topic describes how to perform these tasks for an IAM role that you created to retrieve sensitive data samples from S3 objects. It also provides examples for both scenarios. For information about allowing access to customer managed AWS KMS keys for other scenarios, see KMS key access and permissions in the AWS Key Management Service Developer Guide.

Allowing same-account access to a customer managed key

If the same account owns both the AWS KMS key and the IAM role, a user of the account has to add a statement to the key's policy. The additional statement must allow the IAM role to decrypt data by using the key. For detailed information about updating a key policy, see Changing a key policy in the AWS Key Management Service Developer Guide.

In the statement:

The following is an example of the statement to add to the policy for a KMS key.

{
    "Sid": "Allow the Macie reveal role to use the key",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/IAMRoleName"
    },
    "Action": [
        "kms:Decrypt"
    ],
    "Resource": "*"
}

In the preceding example:

Where you add this statement to a key policy depends on the structure and elements that the policy currently contains. When you add the statement, ensure that the syntax is valid. Key policies use JSON format. This means that you have to also add a comma before or after the statement, depending on where you add the statement to the policy.

Allowing cross-account access to a customer managed key

If one account owns the AWS KMS key (key owner) and a different account owns the IAM role (role owner), the key owner has to provide the role owner with cross-account access to the key. One way to do this is by using a grant. A grant is a policy instrument that allows AWS principals to use KMS keys in cryptographic operations if the conditions specified by the grant are met. To learn about grants, see Grants in AWS KMS in the AWS Key Management Service Developer Guide.

With this approach, the key owner first ensures that the key's policy allows the role owner to create a grant for the key. The role owner then creates a grant for the key. The grant delegates the relevant permissions to the IAM role in their account. It allows the role to decrypt S3 objects that are encrypted with the key.

Step 1: Update the key policy

In the key policy, the key owner should ensure that the policy includes a statement that allows the role owner to create a grant for the IAM role in their (the role owner's) account. In this statement, the Principal element must specify the ARN of the role owner's account. The Action array must specify the kms:CreateGrant action. A Condition block can filter access to the specified action. The following is an example of this statement in the policy for a KMS key.

{
    "Sid": "Allow a role in an account to create a grant",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::111122223333:root"
    },
    "Action": [
        "kms:CreateGrant"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:GranteePrincipal": "arn:aws:iam::111122223333:role/IAMRoleName"
        },
        "ForAllValues:StringEquals": {
            "kms:GrantOperations": "Decrypt"
        }
    }
}

In the preceding example:

Where the key owner adds this statement to the key policy depends on the structure and elements that the policy currently contains. When the key owner adds the statement, they should ensure that the syntax is valid. Key policies use JSON format. This means that the key owner has to also add a comma before or after the statement, depending on where they add the statement to the policy. For detailed information about updating a key policy, see Changing a key policy in the AWS Key Management Service Developer Guide.

Step 2: Create a grant

After the key owner updates the key policy as necessary, the role owner creates a grant for the key. The grant delegates the relevant permissions to the IAM role in their (the role owner's) account. Before the role owner creates the grant, they should verify that they're allowed to perform the kms:CreateGrant action. This action allows them to add a grant to an existing, customer managed AWS KMS key.

To create the grant, the role owner can use the CreateGrant operation of the AWS Key Management Service API. When the role owner creates the grant, they should specify the following values for the required parameters:

If the role owner is using the AWS Command Line Interface (AWS CLI), they can run the create-grant command to create the grant. The following example shows how. The example is formatted for Microsoft Windows and it uses the caret (^) line-continuation character to improve readability.

C:\> aws kms create-grant ^
--key-id arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab ^
--grantee-principal arn:aws:iam::111122223333:role/IAMRoleName ^
--operations "Decrypt"

Where:

If the command runs successfully, you receive output similar to the following.

{
    "GrantToken": "<grant token>",
    "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2"
}

Where GrantToken is a unique, non-secret, variable-length, base64-encoded string that represents the grant that was created, and GrantId is the unique identifier for the grant.