# Investigating sensitive data with Macie findings
When you run sensitive data discovery jobs or Amazon Macie performs automated sensitive data discovery, Macie captures details about the location of each occurrence of sensitive data that it finds in Amazon Simple Storage Service (Amazon S3) objects. This includes sensitive data that Macie detects using [managed data identifiers](managed-data-identifiers.md), and data that matches the criteria of [custom data identifiers](custom-data-identifiers.md) that you configure a job or Macie to use.
With sensitive data findings, you can review these details for as many as 15 occurrences of sensitive data that Macie finds in individual S3 objects. The details provide insight into the breadth of the categories and types of sensitive data that specific S3 buckets and objects might contain. They can help you locate individual occurrences of sensitive data in objects, and determine whether to perform a deeper investigation of specific buckets and objects.
For additional insight, you can optionally configure and use Macie to retrieve samples of sensitive data that Macie reports in individual findings. The samples can help you verify the nature of the sensitive data that Macie found. They can also help you tailor your investigation of an affected S3 bucket and object. If you choose to retrieve sensitive data samples for a finding, Macie uses data in the finding to locate 1-10 occurrences of each type of sensitive data reported by the finding. Macie then extracts those occurrences of sensitive data from the affected object and displays the data for you to review.
If an S3 object contains many occurrences of sensitive data, a finding can also help you navigate to the corresponding sensitive data discovery result. Unlike a sensitive data finding, a sensitive data discovery result provides detailed location data for as many as 1,000 occurrences of each type of sensitive data that Macie finds in an object. Macie uses the same schema for location data in sensitive data findings and sensitive data discovery results. To learn more about sensitive data discovery results, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md).
The topics in this section explain how to locate and optionally retrieve occurrences of sensitive data reported by sensitive data findings. They also explain the schema that Macie uses to report the location of individual occurrences of sensitive data that Macie finds.
**Topics**
+ [Locating sensitive data](findings-locate-sd.md)
+ [Retrieving sensitive data samples](findings-retrieve-sd.md)
+ [Schema for sensitive data locations](findings-locate-sd-schema.md)
# Locating sensitive data with Macie findings
When you run sensitive data discovery jobs or Amazon Macie performs automated sensitive data discovery, Macie performs a deep inspection of the latest version of each Amazon Simple Storage Service (Amazon S3) object that it analyzes. For each job run or analysis cycle, Macie also uses a *depth-first search* algorithm to populate the resulting findings with details about the location of specific occurrences of sensitive data that Macie finds in S3 objects. These occurrences provide insight into the categories and types of sensitive data that an affected S3 bucket and object might contain. The details can help you locate individual occurrences of sensitive data in objects, and determine whether to perform a deeper investigation of specific buckets and objects.
With sensitive data findings, you can determine the location of as many as 15 occurrences of sensitive data that Macie found in an affected S3 object. This includes sensitive data that Macie detected using [managed data identifiers](managed-data-identifiers.md), and data that matches the criteria of [custom data identifiers](custom-data-identifiers.md) that you configured a job or Macie to use.
A sensitive data finding can provide details such as:
+ The column and row number for a cell or field in a Microsoft Excel workbook, CSV file, or TSV file.
+ The path to a field or array in a JSON or JSON Lines file.
+ The line number for a line in a non-binary text file other than a CSV, JSON, JSON Lines, or TSV file—for example, an HTML, TXT, or XML file.
+ The page number for a page in an Adobe Portable Document Format (PDF) file.
+ The record index and the path to a field in a record in an Apache Avro object container or Apache Parquet file.
You can access these details by using the Amazon Macie console or the Amazon Macie API. You can also access these details in findings that Macie publishes to other AWS services, both Amazon EventBridge and AWS Security Hub CSPM. To learn about the JSON structures that Macie uses to report these details, see [Schema for reporting the location of sensitive data](findings-locate-sd-schema.md). To learn how to access the details in findings that Macie publishes to other AWS services, see [Monitoring and processing findings](findings-monitor.md).
If an S3 object contains many occurrences of sensitive data, you can also use a finding to navigate to its corresponding sensitive data discovery result. Unlike a sensitive data finding, a sensitive data discovery result provides detailed location data for as many as 1,000 occurrences of each type of sensitive data that Macie found in an object. If an S3 object is an archive file, such as a .tar or .zip file, this includes occurrences of sensitive data in individual files that Macie extracted from the archive. (Macie doesn’t include this information in sensitive data findings.) To learn more about sensitive data discovery results, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md). Macie uses the same schema for location data in sensitive data findings and sensitive data discovery results.
**To locate sensitive data with findings**
To locate occurrences of sensitive data reported by a finding, you can use the Amazon Macie console or the Amazon Macie API. To do this programmatically, use the [GetFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) operation. If a finding includes details about the location of one or more occurrences of a specific type of sensitive data, `occurrences` objects in the finding provide these details. For more information, see [Schema for reporting the location of sensitive data](findings-locate-sd-schema.md).
To locate occurrences of sensitive data by using the console, follow these steps.
1. Open the Amazon Macie console at [https://console.aws.amazon.com/macie/](https://console.aws.amazon.com/macie/).
1. In the navigation pane, choose **Findings**.
**Tip**
You can quickly display all the findings from a particular sensitive data discovery job. To do this, choose **Jobs** in the navigation pane, and then choose the name of the job. At the top of the details panel, choose **Show results**, and then choose **Show findings**.
1. On the **Findings** page, choose the finding for the sensitive data that you want to locate. The details panel displays information for the finding.
1. In the details panel, scroll to the **Sensitive data** section. This section provides information about the categories and types of sensitive data that Macie found in the affected S3 object. It also indicates the number of occurrences of each type of sensitive data that Macie found.
For example, the following image shows some details of a finding that reports 30 occurrences of credit card numbers, 20 occurrences of names, and 29 occurrences of US Social Security numbers.
![\[The finding details fields that show the number of occurrences of three types of sensitive data.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-sdf-csv-occurrences.png)
If the finding includes details about the location of one or more occurrences of a specific type of sensitive data, the number of occurrences is a link. Choose the link to show the details. Macie opens a new window and displays the details in JSON format.
For example, the following image shows the location of two occurrences of credit card numbers in an affected S3 object.
![\[The location data, in JSON format, for two occurrences of credit card numbers in an S3 object.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-sdf-csv-occurrences-json.png)
To save the details as a JSON file, choose **Download**, and then and specify a name and location for the file.
1. To save all the finding's details as a JSON file, choose the finding's identifier (**Finding ID**) at the top of the details panel. Macie opens a new window and displays all the details in JSON format. Choose **Download**, and then specify a name and location for the file.
To access details about the location of as many as 1,000 occurrences of each type of sensitive data in the affected object, refer to the corresponding sensitive data discovery result for the finding. To do this, scroll to the beginning of the **Details** section of the panel. Then choose the link in the **Detailed result location** field. Macie opens the Amazon S3 console and displays the file or folder that contains the corresponding discovery result.
# Retrieving sensitive data samples with Macie findings
To verify the nature of sensitive data that Amazon Macie reports in findings, you can optionally configure and use Macie to retrieve and reveal samples of sensitive data reported by individual findings. This includes sensitive data that Macie detects using [managed data identifiers](managed-data-identifiers.md), and data that matches the criteria of [custom data identifiers](custom-data-identifiers.md). The samples can help you tailor your investigation of an affected Amazon Simple Storage Service (Amazon S3) object and bucket.
If you retrieve and reveal sensitive data samples for a finding, Macie performs the following general tasks:
1. Verifies that the finding specifies the location of individual occurrences of sensitive data and the location of a corresponding [sensitive data discovery result](discovery-results-repository-s3.md).
1. Evaluates the corresponding sensitive data discovery result, checking the validity of the metadata for the affected S3 object and the location data for occurrences of sensitive data in the object.
1. By using data in the sensitive data discovery result, locates the first 1–10 occurrences of sensitive data reported by the finding, and extracts the first 1–128 characters of each occurrence from the affected S3 object. If the finding reports multiple types of sensitive data, Macie does this for up to 100 types.
1. Encrypts the extracted data with an AWS Key Management Service (AWS KMS) key that you specify.
1. Temporarily stores the encrypted data in a cache and displays the data for you to review. The data is encrypted at all times, both in transit and at rest.
1. Soon after extraction and encryption, permanently deletes the data from the cache unless additional retention is temporarily required to resolve an operational issue.
If you choose to retrieve and reveal sensitive data samples for a finding again, Macie repeats these tasks to locate, extract, encrypt, store, and ultimately delete the samples.
Macie doesn't use the [Macie service-linked role](service-linked-roles.md) for your account to perform these tasks. Instead, you use your AWS Identity and Access Management (IAM) identity or allow Macie to assume an IAM role in your account. You can retrieve and reveal sensitive data samples for a finding if you or the role is allowed to access the requisite resources and data, and perform the requisite actions. All the requisite actions are [logged in AWS CloudTrail](macie-cloudtrail.md).
**Important**
We recommend that you restrict access to this functionality by using [custom IAM policies](security-iam.md). For additional access control, we recommend that you also create a dedicated AWS KMS key for encryption of sensitive data samples that are retrieved, and restrict use of the key to only those principals who must be allowed to retrieve and reveal sensitive data samples.
For recommendations and examples of policies that you might use to control access to this functionality, see the following blog post on the *AWS Security Blog*: [How to use Amazon Macie to preview sensitive data in S3 buckets](https://aws.amazon.com/blogs/security/how-to-use-amazon-macie-to-preview-sensitive-data-in-s3-buckets/).
The topics in this section explain how to configure and use Macie to retrieve and reveal sensitive data samples for findings. You can perform these tasks in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) and Israel (Tel Aviv) Regions.
**Topics**
+ [Configuration options for retrieving samples](findings-retrieve-sd-options.md)
+ [Configuring Macie to retrieve samples](findings-retrieve-sd-configure.md)
+ [Retrieving samples](findings-retrieve-sd-proc.md)
# 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](discovery-results-repository-s3.md) 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](service-linked-roles.md) 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:
+ **Use IAM user credentials** – With this option, each user of your account uses their individual IAM identity to locate, retrieve, encrypt, and reveal the samples. This means that a user can retrieve and reveal sensitive data samples for a finding if they're allowed to access the requisite resources and data, and perform the requisite actions.
+ **Assume an IAM role** – With this option, you create an IAM role that delegates access to Macie. You also ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. Macie then assumes the role when a user of your account chooses to locate, retrieve, encrypt, and reveal sensitive data samples for a finding.
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](https://aws.amazon.com/blogs/security/how-to-use-amazon-macie-to-preview-sensitive-data-in-s3-buckets/).
**Topics**
+ [Determining which access method to use](#findings-retrieve-sd-options-s3access)
+ [Using IAM user credentials to access affected S3 objects](#findings-retrieve-sd-options-s3access-user)
+ [Assuming an IAM role to access affected S3 objects](#findings-retrieve-sd-options-s3access-role)
+ [Configuring an IAM role to access affected S3 objects](#findings-retrieve-sd-options-s3access-role-configuration)
+ [Decrypting affected S3 objects](#findings-retrieve-sd-options-decrypt)
## 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:
+ **Sensitive data discovery jobs** – Only the account that creates a job can access findings that the job produces. If you have a Macie administrator account, you can configure a job to analyze objects in S3 buckets for any account in your organization. Therefore, your jobs can produce findings for objects in buckets that your member accounts own. If you have a member account or a standalone Macie account, you can configure a job to analyze objects only in buckets that your account owns.
+ **Automated sensitive data discovery** – Only the Macie administrator account can access findings that automated discovery produces for accounts in their organization. Member accounts can’t access these findings. If you have a standalone Macie account, you can access findings that automated discovery produces only for your own account.
If you plan to access affected S3 objects by using an IAM role, also consider the following:
+ To locate occurrences of sensitive data in an object, the corresponding sensitive data discovery result for a finding must be stored in an S3 object that Macie signed with a Hash-based Message Authentication Code (HMAC) AWS KMS key. Macie must be able to verify the integrity and authenticity of the sensitive data discovery result. Otherwise, Macie doesn't assume the IAM role to retrieve sensitive data samples. This is an additional guardrail for restricting access to data in S3 objects for an account.
+ To retrieve sensitive data samples from an object that's encrypted with a customer managed AWS KMS key, the IAM role must be allowed to decrypt data with the key. More specifically, the key's policy must allow the role to perform the `kms:Decrypt` action. For other types of server-side encryption, no additional permissions or resources are required to decrypt an affected object. For more information, see [Decrypting affected S3 objects](#findings-retrieve-sd-options-decrypt).
+ To retrieve sensitive data samples from an object for another account, you must currently be the delegated Macie administrator for the account in the applicable AWS Region. In addition:
+ Macie must currently be enabled for the member account in the applicable Region.
+ The member account must have an IAM role that delegates cross-account access to an IAM role in your Macie administrator account. The name of the role must be the same in your Macie administrator account and the member account.
+ The trust policy for the IAM role in the member account must include a condition that specifies the correct external ID for your configuration. This ID is a unique alphanumeric string that Macie generates automatically after you configure the settings for your Macie administrator account. For information about using external IDs in trust policies, see [Access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *AWS Identity and Access Management User Guide*.
+ If the IAM role in the member account meets all Macie requirements, the member account doesn't need to configure and enable Macie settings for you to retrieve sensitive data samples from objects for their account. Macie uses only the settings and IAM role in your Macie administrator account and the IAM role in the member account.
**Tip**
If your account is part of a large organization, consider using an AWS CloudFormation template and stack set to provision and manage the IAM roles for member accounts in your organization. For information about creating and using templates and stack sets, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).
To review and optionally download a CloudFormation template that can serve as a starting point, you can use the Amazon Macie console. In the navigation pane on the console, under **Settings**, choose **Reveal samples**. Choose **Edit**, and then choose **View member role permissions and CloudFormation template**.
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](macie-cloudtrail.md).
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:
1. Verify that you configured a repository for your sensitive data discovery results.
1. Configure the AWS KMS key to use for encryption of sensitive data samples.
1. Verify your permissions for configuring the settings in Macie.
1. Configure and enable the settings in Macie.
For information about performing these tasks, see [Configuring Macie to retrieve sensitive data samples](findings-retrieve-sd-configure.md).
## 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](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) operation of the AWS Security Token Service (AWS STS) API. All the requisite actions are [logged in AWS CloudTrail](macie-cloudtrail.md).
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.
1. Define the following:
+ The name of the IAM role that you want Macie to assume. If your account is part of an organization, this name must be same for the delegated Macie administrator account and each applicable member account in the organization. Otherwise, the Macie administrator won't be able to access affected S3 objects for an applicable member account.
+ The name of the IAM permissions policy to attach to the IAM role. If your account is part of an organization, we recommend that you use the same policy name for each applicable member account in the organization. This can streamline provisioning and managing the role in member accounts.
1. Verify that you configured a repository for your sensitive data discovery results.
1. Configure the AWS KMS key to use for encryption of sensitive data samples.
1. Verify your permissions for creating IAM roles and configuring the settings in Macie.
1. If you're the delegated Macie administrator for an organization or you have a standalone Macie account:
1. Create and configure the IAM role for your account. Ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. For details about these requirements, see the [next topic](#findings-retrieve-sd-options-s3access-role-configuration).
1. Configure and enable the settings in Macie. Macie then generates an external ID for the configuration. If you’re the Macie administrator for an organization, note this ID. The trust policy for the IAM role in each of your applicable member accounts must specify this ID.
1. If you have a member account in an organization:
1. Ask your Macie administrator for the external ID to specify in the trust policy for the IAM role in your account. Also verify the name of the IAM role and permissions policy to create.
1. Create and configure the IAM role for your account. Ensure that the trust and permissions policies for the role meet all requirements for your Macie administrator to assume the role. For details about these requirements, see the [next topic](#findings-retrieve-sd-options-s3access-role-configuration).
1. (Optional) If you want to retrieve and reveal sensitive data samples from affected S3 objects for your own account, configure and enable the settings in Macie. If you want Macie to assume an IAM role to retrieve the samples, start by creating and configuring an additional IAM role in your account. Ensure that the trust and permissions policies for this additional role meet all requirements for Macie to assume the role. Then configure the settings in Macie and specify the name of this additional role. For details about the policy requirements for the role, see the [next topic](#findings-retrieve-sd-options-s3access-role-configuration).
For information about performing these tasks, see [Configuring Macie to retrieve sensitive data samples](findings-retrieve-sd-configure.md).
## 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.
**Note**
If you have a member account in an organization, you might need to create and configure two IAM roles for your account:
To allow your Macie administrator to retrieve and reveal sensitive data samples from affected S3 objects for your account, create and configure a role that your administrator's account can assume. For these details, choose the **Macie member account** section.
To retrieve and reveal sensitive data samples from affected S3 objects for your own account, create and configure a role that Macie can assume. For these details, choose the **Standalone Macie account** section.
Before you create and configure either IAM role, work with your Macie administrator to determine the appropriate configuration for your account.
For detailed information about using IAM to create the role, see [Creating a role using custom trust policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) in the *AWS Identity and Access Management User Guide*.
### Macie administrator account
If you're the delegated Macie administrator for an organization, start by using the IAM policy editor to create the permissions policy for the IAM role. The policy should be as follows.
------
#### [ JSON ]
****
```
{
"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"
}
]
}
```
------
Where *IAMRoleName* is the name of the IAM role for Macie to assume when retrieving sensitive data samples from affected S3 objects for your organization's accounts. Replace this value with the name of the role that you're creating for your account, and planning to create for applicable member accounts in your organization. This name must be the same for your Macie administrator account and each applicable member account.
**Note**
In the preceding permissions policy, the `Resource` element in the first statement uses a wildcard character (`*`). This allows an attached IAM entity to retrieve objects from all the S3 buckets that your organization owns. To allow this access only for specific buckets, replace the wildcard character with the Amazon Resource Name (ARN) of each bucket. For example, to allow access only to objects in a bucket named *amzn-s3-demo-bucket1*, change the element to:
`"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*"`
You can also restrict access to objects in specific S3 buckets for individual accounts. To do this, specify bucket ARNs in the `Resource` element of the permissions policy for the IAM role in each applicable account. For more information and examples, see [IAM JSON policy elements: Resource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html) in the *AWS Identity and Access Management User Guide*.
After you create the permissions policy for the IAM role, create and configure the role. If you do this by using the IAM console, choose **Custom trust policy** as the **Trusted entity type** for the role. For the trust policy that defines trusted entities for the role, specify the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowMacieReveal",
"Effect": "Allow",
"Principal": {
"Service": "reveal-samples.macie.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
Where *111122223333* is the account ID for your AWS account. Replace this value with your 12-digit account ID.
In the preceding trust policy:
+ The `Principal` element specifies the service principal that Macie uses when retrieving sensitive data samples from affected S3 objects, `reveal-samples.macie.amazonaws.com`.
+ The `Action` element specifies the action that the service principal is allowed to perform, the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) operation of the AWS Security Token Service (AWS STS) API.
+ The `Condition` element defines a condition that uses the [aws:SourceAccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context key. This condition determines which account can perform the specified action. In this case, it allows Macie to assume the role only for the specified account. The condition helps prevent Macie from being used as a [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) during transactions with AWS STS.
After you define the trust policy for the IAM role, attach the permissions policy to the role. This should be the permissions policy that you created before you started creating the role. Then complete the remaining steps in IAM to finish creating and configuring the role. When you finish, [configure and enable the settings in Macie](findings-retrieve-sd-configure.md).
### Macie member account
If you have a Macie member account and you want to allow your Macie administrator to retrieve and reveal sensitive data samples from affected S3 objects for your account, start by asking your Macie administrator for the following information:
+ The name of the IAM role to create. The name must be same for your account and the Macie administrator account for your organization.
+ The name of the IAM permissions policy to attach to the role.
+ The external ID to specify in the trust policy for the role. This ID must be the external ID that Macie generated for your Macie administrator's configuration.
After you receive this information, use the IAM policy editor to create the permissions policy for the role. The policy should be as follows.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RetrieveS3Objects",
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"*"
]
}
]
}
```
------
The preceding permissions policy allows an attached IAM entity to retrieve objects from all the S3 buckets for your account. This is because the `Resource` element in the policy uses a wildcard character (`*`). To allow this access only for specific buckets, replace the wildcard character with the Amazon Resource Name (ARN) of each bucket. For example, to allow access only to objects in a bucket named *amzn-s3-demo-bucket2*, change the element to:
`"Resource": "arn:aws:s3:::amzn-s3-demo-bucket2/*"`
For more information and examples, see [IAM JSON policy elements: Resource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html) in the *AWS Identity and Access Management User Guide*.
After you create the permissions policy for the IAM role, create the role. If you create the role by using the IAM console, choose **Custom trust policy** as the **Trusted entity type** for the role. For the trust policy that defines trusted entities for the role, specify the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowMacieAdminRevealRoleForCrossAccountAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/IAMRoleName"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "externalID",
"aws:PrincipalOrgID": "${aws:ResourceOrgID}"
}
}
}
]
}
```
------
In the preceding policy, replace the placeholder values with the correct values for your AWS environment, where:
+ *111122223333* is the 12-digit account ID for your Macie administrator's account.
+ *IAMRoleName* is the name of the IAM role in your Macie administrator's account. It should be the name that you received from your Macie administrator.
+ *externalID* is the external ID that you received from your Macie administrator.
In general, the trust policy allows your Macie administrator to assume the role to retrieve and reveal sensitive data samples from affected S3 objects for your account. The `Principal` element specifies the ARN of an IAM role in your Macie administrator's account. This is the role that your Macie administrator uses to retrieve and reveal sensitive data samples for your organization's accounts. The `Condition` block defines two conditions that further determine who can assume the role:
+ The first condition specifies an external ID that's unique to your organization's configuration. To learn more about external IDs, see [Access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *AWS Identity and Access Management User Guide*.
+ The second condition uses the [aws:PrincipalOrgID](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgid) global condition context key. The value for the key is a dynamic variable that represents the unique identifier for an organization in AWS Organizations (`${aws:ResourceOrgID}`). The condition restricts access to only those accounts that are part of the same organization in AWS Organizations. If you joined your organization by accepting an invitation in Macie, remove this condition from the policy.
After you define the trust policy for the IAM role, attach the permissions policy to the role. This should be the permissions policy that you created before you started creating the role. Then complete the remaining steps in IAM to finish creating and configuring the role. Do not configure and enter settings for the role in Macie.
### Standalone Macie account
If you have a standalone Macie account or a Macie member account and you want to retrieve and reveal sensitive data samples from affected S3 objects for your own account, start by using the IAM policy editor to create the permissions policy for the IAM role. The policy should be as follows.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RetrieveS3Objects",
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"*"
]
}
]
}
```
------
In the preceding permissions policy, the `Resource` element uses a wildcard character (`*`). This allows an attached IAM entity to retrieve objects from all the S3 buckets for your account. To allow this access only for specific buckets, replace the wildcard character with the Amazon Resource Name (ARN) of each bucket. For example, to allow access only to objects in a bucket named *amzn-s3-demo-bucket3*, change the element to:
`"Resource": "arn:aws:s3:::amzn-s3-demo-bucket3/*"`
For more information and examples, see [IAM JSON policy elements: Resource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html) in the *AWS Identity and Access Management User Guide*.
After you create the permissions policy for the IAM role, create the role. If you create the role by using the IAM console, choose **Custom trust policy** as the **Trusted entity type** for the role. For the trust policy that defines trusted entities for the role, specify the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowMacieReveal",
"Effect": "Allow",
"Principal": {
"Service": "reveal-samples.macie.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "999999999999"
}
}
}
]
}
```
------
Where *999999999999* is the account ID for your AWS account. Replace this value with your 12-digit account ID.
In the preceding trust policy:
+ The `Principal` element specifies the service principal that Macie uses when retrieving and revealing sensitive data samples from affected S3 objects, `reveal-samples.macie.amazonaws.com`.
+ The `Action` element specifies the action that the service principal is allowed to perform, the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) operation of the AWS Security Token Service (AWS STS) API.
+ The `Condition` element defines a condition that uses the [aws:SourceAccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context key. This condition determines which account can perform the specified action. It allows Macie to assume the role only for the specified account. The condition helps prevent Macie from being used as a [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) during transactions with AWS STS.
After you define the trust policy for the IAM role, attach the permissions policy to the role. This should be the permissions policy that you created before you started creating the role. Then complete the remaining steps in IAM to finish creating and configuring the role. When you finish, [configure and enable the settings in Macie](findings-retrieve-sd-configure.md).
## 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](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) 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:
+ If the same account owns the KMS key and the role, a user of the account has to update the key's policy.
+ If one account owns the KMS key and a different account owns the role, a user of the account that owns the key has to allow cross-account access to the key.
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](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) 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](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) in the *AWS Key Management Service Developer Guide*.
In the statement:
+ The `Principal` element must specify the Amazon Resource Name (ARN) of the IAM role.
+ The `Action` array must specify the `kms:Decrypt` action. This is the only AWS KMS action that the IAM role must be allowed to perform to decrypt an object that's encrypted with the key.
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:
+ The `AWS` field in the `Principal` element specifies the ARN of the IAM role in the account. It allows the role to perform the action specified by the policy statement. *123456789012* is an example account ID. Replace this value with the account ID for the account that owns the role and the KMS key. *IAMRoleName* is an example name. Replace this value with the name of the IAM role in the account.
+ The `Action` array specifies the action that the IAM role is allowed to perform using the KMS key—decrypt ciphertext that's encrypted with the key.
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](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) 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:
+ The `AWS` field in the `Principal` element specifies the ARN of the role owner's account. It allows the account to perform the action specified by the policy statement. *111122223333* is an example account ID. Replace this value with the account ID for the role owner's account.
+ The `Action` array specifies the action that the role owner is allowed to perform on the KMS key—create a grant for the key.
+ The `Condition` block uses [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) and the following condition keys to filter access to the action that the role owner is allowed to perform on the KMS key:
+ [kms:GranteePrincipal](https://docs.aws.amazon.com/kms/latest/developerguide/conditions-kms.html#conditions-kms-grantee-principal) – This condition allows the role owner to create a grant only for the specified grantee principal, which is the ARN of the IAM role in their account. In that ARN, *111122223333* is an example account ID. Replace this value with the account ID for the role owner's account. *IAMRoleName* is an example name. Replace this value with the name of the IAM role in the role owner's account.
+ [kms:GrantOperations](https://docs.aws.amazon.com/kms/latest/developerguide/conditions-kms.html#conditions-kms-grant-operations) – This condition allows the role owner to create a grant only to delegate permission to perform the AWS KMS `Decrypt` action (decrypt ciphertext that's encrypted with the key). It prevents the role owner from creating grants that delegate permissions to perform other actions on the KMS key. The `Decrypt` action is the only AWS KMS action that the IAM role must be allowed to perform to decrypt an object that's encrypted with the key.
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](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) 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:
+ `KeyId` – The ARN of the KMS key. For cross-account access to a KMS key, this value must be an ARN. It can't be a key ID.
+ `GranteePrincipal` – The ARN of the IAM role in their account. This value should be `arn:aws:iam::111122223333:role/IAMRoleName`, where *111122223333* is the account ID for the role owner's account and *IAMRoleName* is the name of the role.
+ `Operations` – The AWS KMS decrypt action (`Decrypt`). This is the only AWS KMS action that the IAM role must be allowed to perform to decrypt an object that's encrypted with the KMS key.
If the role owner is using the AWS Command Line Interface (AWS CLI), they can run the [create-grant](https://docs.aws.amazon.com/cli/latest/reference/kms/create-grant.html) 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:
+ `key-id` specifies the ARN of the KMS key to apply the grant to.
+ `grantee-principal` specifies the ARN of the IAM role that's allowed to perform the action specified by the grant. This value should match the ARN specified by the `kms:GranteePrincipal` condition in the key policy.
+ `operations` specifies the action that the grant allows the specified principal to perform—decrypt ciphertext that's encrypted with the key.
If the command runs successfully, you receive output similar to the following.
```
{
"GrantToken": "",
"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.
# Configuring Macie to retrieve sensitive data samples
You can optionally configure and use Amazon Macie to retrieve and reveal samples of sensitive data that Macie reports in individual findings. The samples can help you verify the nature of the sensitive data that Macie found. They can also help you tailor your investigation of an affected Amazon Simple Storage Service (Amazon S3) object and bucket. You can retrieve and reveal sensitive data samples in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) and Israel (Tel Aviv) Regions.
When 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 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.
To retrieve and reveal sensitive data samples for findings, you first need to configure and enable settings for your Macie account. You also need to configure supporting resources and permissions for your account. The topics in this section guide you through the process of configuring Macie to retrieve and reveal sensitive data samples, and managing the status of the configuration for your account.
**Topics**
+ [Before you begin](#findings-retrieve-sd-configure-prereqs)
+ [Configuring and enabling Macie settings](#findings-retrieve-sd-configure-enable)
+ [Disabling Macie settings](#findings-retrieve-sd-configure-manage)
**Tip**
For recommendations and examples of policies that you might use to control access to this functionality, see the following blog post on the *AWS Security Blog*: [How to use Amazon Macie to preview sensitive data in S3 buckets](https://aws.amazon.com/blogs/security/how-to-use-amazon-macie-to-preview-sensitive-data-in-s3-buckets/).
## Before you begin
Before you configure Amazon Macie to retrieve and reveal sensitive data samples for findings, complete the following tasks to ensure that you have the resources and permissions that you need.
**Topics**
+ [Step 1: Configure a repository for sensitive data discovery results](#findings-retrieve-sd-configure-sddr)
+ [Step 2: Determine how to access affected S3 objects](#findings-retrieve-sd-configure-s3access)
+ [Step 3: Configure an AWS KMS key](#findings-retrieve-sd-configure-key)
+ [Step 4: Verify your permissions](#findings-retrieve-sd-configure-permissions)
These tasks are optional if you've already configured Macie to retrieve and reveal sensitive data samples and only want to change your configuration settings.
### Step 1: Configure a repository for sensitive data discovery results
When 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 S3 object. Therefore, it's important to verify that you configured a repository for your sensitive data discovery results. Otherwise, Macie won't be able to locate sensitive data samples that you want to retrieve and reveal.
To determine whether you've configured this repository for your account, you can use the Amazon Macie console: choose **Discovery results** (under **Settings**) in the navigation pane. To do this programmatically, use the [GetClassificationExportConfiguration](https://docs.aws.amazon.com/macie/latest/APIReference/classification-export-configuration.html) operation of the Amazon Macie API. To learn more about sensitive data discovery results and how to configure this repository, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md).
### Step 2: Determine how to access affected S3 objects
To access affected S3 objects and retrieve sensitive data samples from them, you have two options. You can configure Macie to use your AWS Identity and Access Management (IAM) user credentials. Or you can configure Macie to assume an IAM role that delegates access to Macie. 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. Before you configure the settings in Macie, determine which access method you want to use. For details about the options and requirements for each method, see [Configuration options for retrieving samples](findings-retrieve-sd-options.md).
If you plan to use an IAM role, create and configure the role before you configure the settings in Macie. Also ensure that the trust and permissions policies for the role meet all requirements for Macie to assume the role. If your account is part of an organization that centrally manages multiple Macie accounts, work with your Macie administrator to first determine whether and how to configure the role for your account.
### Step 3: Configure an AWS KMS key
When you retrieve and reveal sensitive data samples for a finding, Macie encrypts the samples with an AWS Key Management Service (AWS KMS) key that you specify. Therefore, you need to determine which AWS KMS key you want to use to encrypt the samples. The key can be an existing KMS key from your own account, or an existing KMS key that another account owns. If you want to use a key that another account owns, obtain the Amazon Resource Name (ARN) of the key. You'll need to specify this ARN when you enter the configuration settings in Macie.
The KMS key must be a customer managed, symmetric encryption key. It must also be a single-Region key that's enabled in the same AWS Region as your Macie account. The KMS key can be in an external key store. However, the key might then be slower and less reliable than a key that’s managed entirely within AWS KMS. If latency or an availability issue prevents Macie from encrypting sensitive data samples that you want to retrieve and reveal, an error occurs and Macie doesn't return any samples for the finding.
In addition, the key policy for the key must allow the appropriate principals (IAM roles, IAM users, or AWS accounts) to perform the following actions:
+ `kms:Decrypt`
+ `kms:DescribeKey`
+ `kms:GenerateDataKey`
**Important**
As an additional layer of access control, we recommend that you create a dedicated KMS key for encryption of sensitive data samples that are retrieved, and restrict use of the key to only those principals who must be allowed to retrieve and reveal sensitive data samples. If a user isn't allowed to perform the preceding actions for the key, Macie rejects their request to retrieve and reveal sensitive data samples. Macie doesn't return any samples for the finding.
For information about creating and configuring KMS keys, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*. For information about using key policies to manage access to KMS keys, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*.
### Step 4: Verify your permissions
Before you configure the settings in Macie, also verify that you have the permissions that you need. To verify your permissions, use AWS Identity and Access Management (IAM) to review the IAM policies that are attached to your IAM identity. Then compare the information in those policies to the following list of actions that you must be allowed to perform.
**Amazon Macie**
For Macie, verify that you're allowed to perform the following actions:
+ `macie2:GetMacieSession`
+ `macie2:UpdateRevealConfiguration`
The first action allows you to access your Macie account. The second action allows you to change your configuration settings for retrieving and revealing sensitive data samples. This includes enabling and disabling the configuration for your account.
Optionally verify that you're also allowed to perform the `macie2:GetRevealConfiguration` action. This action allows you to retrieve your current configuration settings and the current status of the configuration for your account.
**AWS KMS**
If you plan to use the Amazon Macie console to enter the configuration settings, also verify that you're allowed to perform the following AWS Key Management Service (AWS KMS) actions:
+ `kms:DescribeKey`
+ `kms:ListAliases`
These actions allow you to retrieve information about the AWS KMS keys for your account. You can then choose one of these keys when you enter the settings.
**IAM**
If you plan to configure Macie to assume an IAM role to retrieve and reveal sensitive data samples, also verify that you're allowed to perform the following IAM action: `iam:PassRole`. This action allows you to pass the role to Macie, which in turn allows Macie to assume the role. When you enter the configuration settings for your account, Macie can also then verify that the role exists in your account and is configured correctly.
If you're not allowed to perform the requisite actions, ask your AWS administrator for assistance.
## Configuring and enabling Macie settings
After you verify that you have the resources and permissions that you need, you can configure the settings in Amazon Macie and enable the configuration for your account.
If your account is part of an organization that centrally manages multiple Macie accounts, note the following before you configure or subsequently change the settings for your account:
+ If you have a member account, work with your Macie administrator to determine whether and how to configure the settings for your account. Your Macie administrator can help you determine the correct configuration settings for your account.
+ If you have a Macie administrator account and you change your settings for accessing affected S3 objects, your changes might affect other accounts and resources for your organization. This depends on whether Macie is currently configured to assume an AWS Identity and Access Management (IAM) role to retrieve sensitive data samples. If it is and you reconfigure Macie to use IAM user credentials, Macie permanently deletes existing settings for the IAM role—the name of the role and the external ID for your configuration. If your organization subsequently chooses to use IAM roles again, you'll need to specify a new external ID in the trust policy for the role in each applicable member account.
For details about the configuration options and requirements for either type of account, see [Configuration options for retrieving samples](findings-retrieve-sd-options.md).
To configure the settings in Macie and enable the configuration for your account, you can use the Amazon Macie console or the Amazon Macie API.
------
#### [ Console ]
Follow these steps to configure and enable the settings by using the Amazon Macie console.
**To configure and enable Macie settings**
1. Open the Amazon Macie console at [https://console.aws.amazon.com/macie/](https://console.aws.amazon.com/macie/).
1. By using the AWS Region selector in the upper-right corner of the page, choose the Region in which you want to configure and enable Macie to retrieve and reveal sensitive data samples.
1. In the navigation pane, under **Settings**, choose **Reveal samples**.
1. In the **Settings** section, choose **Edit**.
1. For **Status**, choose **Enable**.
1. Under **Access**, specify the access method and settings that you want to use when retrieving sensitive data samples from affected S3 objects:
+ To use an IAM role that delegates access to Macie, choose **Assume an IAM role**. If you choose this option, Macie retrieves the samples by assuming the IAM role that you created and configured in your AWS account. In the **Role name** box, enter the name of the role.
+ To use the credentials of the IAM user who requests the samples, choose **Use IAM user credentials**. If you choose this option, each user of your account uses their individual IAM identity to retrieve the samples.
1. Under **Encryption**, specify the AWS KMS key that you want to use to encrypt sensitive data samples that are retrieved:
+ To use a KMS key from your own account, choose **Select a key from your account**. Then, in the **AWS KMS key** list, choose the key to use. The list displays existing, symmetric encryption KMS keys for your account.
+ To use a KMS key that another account owns, choose **Enter the ARN of a key from another account**. Then, in the **AWS KMS key ARN** box, enter the Amazon Resource Name (ARN) of the key to use—for example, **arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab**.
1. When you finish entering the settings, choose **Save**.
Macie tests the settings and verifies that they're correct. If you configured Macie to assume an IAM role, Macie also verifies that the role exists in your account and the trust and permissions policies are configured correctly. If there's an issue, Macie displays a message that describes the issue.
To address an issue with the AWS KMS key, refer to the requirements in the [preceding topic](#findings-retrieve-sd-configure-key) and specify a KMS key that meets the requirements. To address an issue with the IAM role, start by verifying that you entered the correct role name. If the name is correct, ensure that the role’s policies meet all requirements for Macie to assume the role. For these details, see [Configuring an IAM role to access affected S3 objects](findings-retrieve-sd-options.md#findings-retrieve-sd-options-s3access-role-configuration). After you address any issues, you can save and enable the settings.
**Note**
If you're the Macie administrator for an organization and you configured Macie to assume an IAM role, Macie generates and displays an external ID after you save the settings for your account. Note this ID. The trust policy for the IAM role in each of your applicable member accounts must specify this ID. Otherwise, you won't be able to retrieve sensitive data samples from S3 objects that the accounts own.
------
#### [ API ]
To configure and enable the settings programmatically, use the [UpdateRevealConfiguration](https://docs.aws.amazon.com/macie/latest/APIReference/reveal-configuration.html) operation of the Amazon Macie API. In your request, specify the appropriate values for the supported parameters:
+ For the `retrievalConfiguration` parameters, specify the access method and settings that you want to use when retrieving sensitive data samples from affected S3 objects:
+ To assume an IAM role that delegates access to Macie, specify `ASSUME_ROLE` for the `retrievalMode` parameter and specify the name of the role for the `roleName` parameter. If you specify these settings, Macie retrieves the samples by assuming the IAM role that you created and configured in your AWS account.
+ To use the credentials of the IAM user who requests the samples, specify `CALLER_CREDENTIALS` for the `retrievalMode` parameter. If you specify this setting, each user of your account uses their individual IAM identity to retrieve the samples.
**Important**
If you don't specify values for these parameters, Macie sets the access method (`retrievalMode`) to `CALLER_CREDENTIALS`. If Macie is currently configured to use an IAM role to retrieve the samples, Macie also permanently deletes the current role name and external ID for your configuration. To keep these settings for an existing configuration, include the `retrievalConfiguration` parameters in your request and specify your current settings for those parameters. To retrieve your current settings, use the [GetRevealConfiguration](https://docs.aws.amazon.com/macie/latest/APIReference/reveal-configuration.html) operation or, if you're using the AWS Command Line Interface (AWS CLI), run the [get-reveal-configuration](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-reveal-configuration.html) command.
+ For the `kmsKeyId` parameter, specify the AWS KMS key that you want to use to encrypt sensitive data samples that are retrieved:
+ To use a KMS key from your own account, specify the Amazon Resource Name (ARN), ID, or alias for the key. If you specify an alias, include the `alias/` prefix—for example, `alias/ExampleAlias`.
+ To use a KMS key that another account owns, specify the ARN of the key—for example, `arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`. Or specify the ARN of the alias for the key—for example, `arn:aws:kms:us-east-1:111122223333:alias/ExampleAlias`.
+ For the `status` parameter, specify `ENABLED` to enable the configuration for your Macie account.
In your request, also ensure that you specify the AWS Region in which you want to enable and use the configuration.
To configure and enable the settings by using the AWS CLI, run the [update-reveal-configuration](https://docs.aws.amazon.com/cli/latest/reference/macie2/update-reveal-configuration.html) command and specify the appropriate values for the supported parameters. For example, if you're using the AWS CLI on Microsoft Windows, run the following command:
```
C:\> aws macie2 update-reveal-configuration ^
--region us-east-1 ^
--configuration={\"kmsKeyId\":\"arn:aws:kms:us-east-1:111122223333:alias/ExampleAlias\",\"status\":\"ENABLED\"} ^
--retrievalConfiguration={\"retrievalMode\":\"ASSUME_ROLE\",\"roleName\":\"MacieRevealRole\"}
```
Where:
+ *us-east-1* is the Region in which to enable and use the configuration. In this example, the US East (N. Virginia) Region.
+ *arn:aws:kms:us-east-1:111122223333:alias/ExampleAlias* is the ARN of the alias for the AWS KMS key to use. In this example, the key is owned by another account.
+ `ENABLED` is the status of the configuration.
+ *ASSUME\$1ROLE* is the access method to use. In this example, assume the specified IAM role.
+ *MacieRevealRole* is the name of the IAM role for Macie to assume when retrieving sensitive data samples.
The preceding example uses the caret (^) line-continuation character to improve readability.
When you submit your request, Macie tests the settings. If you configured Macie to assume an IAM role, Macie also verifies that the role exists in your account and the trust and permissions policies are configured correctly. If there's an issue, your request fails and Macie returns a message that describes the issue. To address an issue with the AWS KMS key, refer to the requirements in the [preceding topic](#findings-retrieve-sd-configure-key) and specify a KMS key that meets the requirements. To address an issue with the IAM role, start by verifying that you specified the correct role name. If the name is correct, ensure that the role’s policies meet all requirements for Macie to assume the role. For these details, see [Configuring an IAM role to access affected S3 objects](findings-retrieve-sd-options.md#findings-retrieve-sd-options-s3access-role-configuration). After you address the issue, submit your request again.
If your request succeeds, Macie enables the configuration for your account in the specified Region and you receive output similar to the following.
```
{
"configuration": {
"kmsKeyId": "arn:aws:kms:us-east-1:111122223333:alias/ExampleAlias",
"status": "ENABLED"
},
"retrievalConfiguration": {
"externalId": "o2vee30hs31642lexample",
"retrievalMode": "ASSUME_ROLE",
"roleName": "MacieRevealRole"
}
}
```
Where `kmsKeyId` specifies the AWS KMS key to use to encrypt sensitive data samples that are retrieved, and `status` is the status of the configuration for your Macie account. The `retrievalConfiguration` values specify the access method and settings to use when retrieving the samples.
**Note**
If you're the Macie administrator for an organization and you configured Macie to assume an IAM role, note the external ID (`externalId`) in the response. The trust policy for the IAM role in each of your applicable member accounts must specify this ID. Otherwise, you won't be able to retrieve sensitive data samples from affected S3 objects that the accounts own.
To subsequently check the settings or status of the configuration for your account, use the [GetRevealConfiguration](https://docs.aws.amazon.com/macie/latest/APIReference/reveal-configuration.html) operation or, for the AWS CLI, run the [get-reveal-configuration](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-reveal-configuration.html) command.
------
## Disabling Macie settings
You can disable the configuration settings for your Amazon Macie account at any time. If you disable the configuration, Macie retains the setting that specifies which AWS KMS key to use to encrypt sensitive data samples that are retrieved. Macie permanently deletes the Amazon S3 access settings for the configuration.
**Warning**
When you disable the configuration settings for your Macie account, you also permanently delete current settings that specify how to access affected S3 objects. If Macie is currently configured to access affected objects by assuming an AWS Identity and Access Management (IAM) role, this includes: the name of the role, and the external ID that Macie generated for the configuration. These settings can't be recovered after they're deleted.
To disable the configuration settings for your Macie account, you can use the Amazon Macie console or the Amazon Macie API.
------
#### [ Console ]
Follow these steps to disable the configuration settings for your account by using the Amazon Macie console.
**To disable Macie settings**
1. Open the Amazon Macie console at [https://console.aws.amazon.com/macie/](https://console.aws.amazon.com/macie/).
1. By using the AWS Region selector in the upper-right corner of the page, choose the Region in which you want to disable the configuration settings for your Macie account.
1. In the navigation pane, under **Settings**, choose **Reveal samples**.
1. In the **Settings** section, choose **Edit**.
1. For **Status**, choose **Disable**.
1. Choose **Save**.
------
#### [ API ]
To disable the configuration settings programmatically, use the [UpdateRevealConfiguration](https://docs.aws.amazon.com/macie/latest/APIReference/reveal-configuration.html) operation of the Amazon Macie API. In your request, ensure that you specify the AWS Region in which you want to disable the configuration. For the `status` parameter, specify `DISABLED`.
To disable the configuration settings by using the AWS Command Line Interface (AWS CLI), run the [update-reveal-configuration](https://docs.aws.amazon.com/cli/latest/reference/macie2/update-reveal-configuration.html) command. Use the `region` parameter to specify the Region in which you want to disable the configuration. For the `status` parameter, specify `DISABLED`. For example, if you're using the AWS CLI on Microsoft Windows, run the following command:
```
C:\> aws macie2 update-reveal-configuration --region us-east-1 --configuration={\"status\":\"DISABLED\"}
```
Where:
+ *us-east-1* is the Region in which to disable the configuration. In this example, the US East (N. Virginia) Region.
+ `DISABLED` is the new status of the configuration.
If your request succeeds, Macie disables the configuration for your account in the specified Region and you receive output similar to the following.
```
{
"configuration": {
"status": "DISABLED"
}
}
```
Where `status` is the new status of the configuration for your Macie account.
------
If Macie was configured to assume an IAM role to retrieve sensitive data samples, you can optionally delete the role and the role's permissions policy. Macie doesn't delete these resources when you disable the configuration settings for your account. In addition, Macie doesn't use these resources to perform any other tasks for your account. To delete the role and its permissions policy, you can use the IAM console or the IAM API. For more information, see [Deleting roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html) in the *AWS Identity and Access Management User Guide*.
# Retrieving sensitive data samples for a Macie finding
By using Amazon Macie, you can retrieve and reveal samples of sensitive data that Macie reports in individual sensitive data findings. This includes sensitive data that Macie detects using [managed data identifiers](managed-data-identifiers.md), and data that matches the criteria of [custom data identifiers](custom-data-identifiers.md). The samples can help you verify the nature of the sensitive data that Macie found. They can also help you tailor your investigation of an affected Amazon Simple Storage Service (Amazon S3) object and bucket. You can retrieve and reveal sensitive data samples in all the AWS Regions where Macie is currently available except the Asia Pacific (Osaka) and Israel (Tel Aviv) Regions.
If you retrieve and reveal sensitive data samples for a finding, Macie uses data in the corresponding [sensitive data discovery result](discovery-results-repository-s3.md) to locate the first 1–10 occurrences of sensitive data reported by the finding. Macie then extracts the first 1–128 characters of each occurrence from the affected S3 object. If a finding reports multiple types of sensitive data, Macie does this for up to 100 types of sensitive data reported by the finding.
When Macie extracts sensitive data from an affected S3 object, Macie encrypts the 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.
If you choose to retrieve and reveal sensitive data samples for a finding again, Macie repeats the process for locating, extracting, encrypting, storing, and ultimately deleting the samples.
For a demonstration of how you can retrieve and reveal sensitive data samples by using the Amazon Macie console, watch the following video:
**Topics**
+ [Before you begin](#findings-retrieve-sd-proc-prereqs)
+ [Determining whether samples are available for a finding](#findings-retrieve-sd-proc-criteria)
+ [Retrieving samples for a finding](#findings-retrieve-sd-proc-steps)
## Before you begin
Before you can retrieve and reveal sensitive data samples for findings, you need to [configure and enable settings for your Amazon Macie account](findings-retrieve-sd-configure.md). You also need to work with your AWS administrator to verify that you have the permissions and resources that you need.
When you retrieve and reveal sensitive data samples for a finding, Macie performs a series of tasks to locate, retrieve, encrypt, and reveal the samples. Macie doesn't use the [Macie service-linked role](service-linked-roles.md) for your account to perform these tasks. Instead, you use your AWS Identity and Access Management (IAM) identity or allow Macie to assume an IAM role in your account.
To retrieve and reveal sensitive data samples for a finding, you must have access to the finding, the corresponding sensitive data discovery result, and the AWS KMS key that you configured Macie to use to encrypt sensitive data samples. In addition, you or the IAM role must be allowed to access the affected S3 bucket and the affected S3 object. You or 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, an error occurs and Macie doesn't return any samples for the finding.
You must also be allowed to perform the following Macie actions:
+ `macie2:GetMacieSession`
+ `macie2:GetFindings`
+ `macie2:ListFindings`
+ `macie2:GetSensitiveDataOccurrences`
The first three actions allow you to access your Macie account and retrieve the details of findings. The last action allows you to retrieve and reveal sensitive data samples for findings.
To use the Amazon Macie console to retrieve and reveal sensitive data samples, you must also be allowed to perform the following action: `macie2:GetSensitiveDataOccurrencesAvailability`. This action allows you to determine whether samples are available for individual findings. You don't need permission to perform this action to retrieve and reveal samples programmatically. However, having this permission can streamline your retrieval of samples.
If you're the delegated Macie administrator for an organization and you configured Macie to assume an IAM role to retrieve sensitive data samples, you must also be allowed to perform the following action: `macie2:GetMember`. This action allows you to retrieve information about the association between your account and an affected account. It enables Macie to verify that you're currently the Macie administrator for the affected account.
If you're not allowed to perform the requisite actions or access the requisite data and resources, ask your AWS administrator for assistance.
## Determining whether sensitive data samples are available for a finding
To retrieve and reveal sensitive data samples for a finding, the finding needs to meet certain criteria. It has to include location data for specific occurrences of sensitive data. In addition, it has to specify the location of a valid, corresponding sensitive data discovery result. The sensitive data discovery result must be stored in the same AWS Region as the finding. If you configured Amazon Macie to access affected S3 objects by assuming an AWS Identity and Access Management (IAM) role, the sensitive data discovery result must also be stored in an S3 object that Macie signed with a Hash-based Message Authentication Code (HMAC) AWS KMS key.
The affected S3 object also needs to meet certain criteria. The MIME type of the object must be one of the following:
+ *application/avro*, for an Apache Avro object container (.avro) file
+ *application/gzip*, for a GNU Zip compressed archive (.gz or .gzip) file
+ *application/json*, for a JSON or JSON Lines (.json or .jsonl) file
+ *application/parquet*, for an Apache Parquet (.parquet) file
+ *application/vnd.openxmlformats-officedocument.spreadsheetml.sheet*, for a Microsoft Excel workbook (.xlsx) file
+ *application/zip*, for a ZIP compressed archive (.zip) file
+ *text/csv*, for a CSV (.csv) file
+ *text/plain*, for a non-binary text file other than a CSV, JSON, JSON Lines, or TSV file
+ *text/tab-separated-values*, for a TSV (.tsv) file
In addition, the contents of the S3 object must be the same as when the finding was created. Macie checks the object's entity tag (ETag) to determine whether it matches the ETag specified by the finding. Also, the storage size of the object can't exceed the applicable size quota for retrieving and revealing sensitive data samples. For a list of applicable quotas, see [Quotas for Macie](macie-quotas.md).
If a finding and the affected S3 object meet the preceding criteria, sensitive data samples are available for the finding. You can optionally determine whether this is the case for a particular finding before you try to retrieve and reveal samples for it.
**To determine whether sensitive data samples are available for a finding**
You can use the Amazon Macie console or the Amazon Macie API to determine whether sensitive data samples are available for a finding.
------
#### [ Console ]
Follow these steps on the Amazon Macie console to determine whether sensitive data samples are available for a finding.
**To determine whether samples are available for a finding**
1. Open the Amazon Macie console at [https://console.aws.amazon.com/macie/](https://console.aws.amazon.com/macie/).
1. In the navigation pane, choose **Findings**.
1. On the **Findings** page, choose the finding. The details panel displays information for the finding.
1. In the details panel, scroll to the **Sensitive data** section. Then refer to the **Reveal samples** field.
If sensitive data samples are available for the finding, a **Review** link appears in the field, as shown in the following image.
![\[The Reveal samples field in the finding details panel. The field contains a link labeled Review.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-reveal-samples.png)
If sensitive data samples aren't available for the finding, the **Reveal samples** field displays text indicating why:
+ **Account not in organization** – You're not allowed to access the affected S3 object by using Macie. The affected account isn't currently part of your organization. Or the account is part of your organization but Macie isn't currently enabled for the account in the current AWS Region.
+ **Invalid classification result** – There isn't a corresponding sensitive data discovery result for the finding. Or the corresponding sensitive data discovery result isn't available in the current AWS Region, is malformed or corrupted, or uses an unsupported storage format. Macie can't verify the location of the sensitive data to retrieve.
+ **Invalid result signature** – The corresponding sensitive data discovery result is stored in an S3 object that wasn't signed by Macie. Macie can't verify the integrity and authenticity of the sensitive data discovery result. Therefore, Macie can't verify the location of the sensitive data to retrieve.
+ **Member role too permissive** – The trust or permissions policy for the IAM role in the affected member account doesn't meet Macie requirements for restricting access to the role. Or the role's trust policy doesn't specify the correct external ID for your organization. Macie can’t assume the role to retrieve the sensitive data.
+ **Missing GetMember permission** – You're not allowed to retrieve information about the association between your account and the affected account. Macie can't determine whether you’re allowed to access the affected S3 object as the delegated Macie administrator for the affected account.
+ **Object exceeds size quota** – The storage size of the affected S3 object exceeds the size quota for retrieving and revealing samples of sensitive data from that type of file.
+ **Object unavailable** – The affected S3 object isn't available. The object was renamed, moved, or deleted, or its contents changed after Macie created the finding. Or the object is encrypted with an AWS KMS key that isn’t available. For example, the key is disabled, is scheduled for deletion, or was deleted.
+ **Result not signed** – The corresponding sensitive data discovery result is stored in an S3 object that hasn't been signed. Macie can't verify the integrity and authenticity of the sensitive data discovery result. Therefore, Macie can't verify the location of the sensitive data to retrieve.
+ **Role too permissive** – Your account is configured to retrieve occurrences of sensitive data by using an IAM role whose trust or permissions policy doesn't meet Macie requirements for restricting access to the role. Macie can’t assume the role to retrieve the sensitive data.
+ **Unsupported object type** – The affected S3 object uses a file or storage format that Macie doesn't support for retrieving and revealing samples of sensitive data. The MIME type of the affected S3 object isn't one of the values in the [preceding list](#findings-retrieve-sd-criteria-mimetype).
If there's an issue with the sensitive data discovery result for the finding, the information in the **Detailed result location** field of the finding can help you investigate the issue. This field specifies the original path to the result in Amazon S3. To investigate an issue with an IAM role, ensure that the role's policies meet all requirements for Macie to assume the role. For these details, see [Configuring an IAM role to access affected S3 objects](findings-retrieve-sd-options.md#findings-retrieve-sd-options-s3access-role-configuration).
------
#### [ API ]
To programmatically determine whether sensitive data samples are available for a finding, use the [GetSensitiveDataOccurrencesAvailability](https://docs.aws.amazon.com/macie/latest/APIReference/findings-findingid-reveal-availability.html) operation of the Amazon Macie API. When you submit your request, use the `findingId` parameter to specify the unique identifier for the finding. To obtain this identifier, you can use the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) operation.
If you're using the AWS Command Line Interface (AWS CLI), run the [get-sensitive-data-occurrences-availability](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-sensitive-data-occurrences-availability.html) command and use the `finding-id` parameter to specify the unique identifier for the finding. To obtain this identifier, you can run the [list-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings.html) command.
If your request succeeds and samples are available for the finding, you receive output similar to the following:
```
{
"code": "AVAILABLE",
"reasons": []
}
```
If your request succeeds and samples aren't available for the finding, the value for the `code` field is `UNAVAILABLE` and the `reasons` array specifies why. For example:
```
{
"code": "UNAVAILABLE",
"reasons": [
"UNSUPPORTED_OBJECT_TYPE"
]
}
```
If there's an issue with the sensitive data discovery result for the finding, the information in the `classificationDetails.detailedResultsLocation` field of the finding can help you investigate the issue. This field specifies the original path to the result in Amazon S3. To investigate an issue with an IAM role, ensure that the role's policies meet all requirements for Macie to assume the role. For these details, see [Configuring an IAM role to access affected S3 objects](findings-retrieve-sd-options.md#findings-retrieve-sd-options-s3access-role-configuration).
------
## Retrieving sensitive data samples for a finding
To retrieve and reveal sensitive data samples for a finding, you can use the Amazon Macie console or the Amazon Macie API.
------
#### [ Console ]
Follow these steps to retrieve and reveal sensitive data samples for a finding by using the Amazon Macie console.
**To retrieve and reveal sensitive data samples for a finding**
1. Open the Amazon Macie console at [https://console.aws.amazon.com/macie/](https://console.aws.amazon.com/macie/).
1. In the navigation pane, choose **Findings**.
1. On the **Findings** page, choose the finding. The details panel displays information for the finding.
1. In the details panel, scroll to the **Sensitive data** section. Then, in the **Reveal samples** field, choose **Review**:
![\[The Reveal samples field in the finding details panel. The field contains a link labeled Review.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-reveal-samples.png)
**Note**
If the **Review** link doesn't appear in the **Reveal samples** field, sensitive data samples aren't available for the finding. To determine why this is the case, see the [preceding topic](#findings-retrieve-sd-proc-criteria).
After you choose **Review**, Macie displays a page that summarizes key details of the finding. The details include the categories, types, and number of occurrences of sensitive data that Macie found in the affected S3 object.
1. In the **Sensitive data** section of the page, choose **Reveal samples**. Macie then retrieves and reveals samples of the first 1–10 occurrences of sensitive data reported by the finding. Each sample contains the first 1–128 characters of an occurrence of sensitive data. It can take several minutes to retrieve and reveal the samples.
If the finding reports multiple types of sensitive data, Macie retrieves and reveals samples for up to 100 types. For example, the following image shows samples that span multiple categories and types of sensitive data—AWS credentials, US phone numbers, and people's names.
![\[The samples table. It lists nine samples and each sample's sensitive data category and type.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-sd-samples.png)
The samples are organized first by sensitive data category, and then by sensitive data type.
------
#### [ API ]
To retrieve and reveal sensitive data samples for a finding programmatically, use the [GetSensitiveDataOccurrences](https://docs.aws.amazon.com/macie/latest/APIReference/findings-findingid-reveal.html) operation of the Amazon Macie API. When you submit your request, use the `findingId` parameter to specify the unique identifier for the finding. To obtain this identifier, you can use the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) operation.
To retrieve and reveal sensitive data samples by using the AWS Command Line Interface (AWS CLI), run the [get-sensitive-data-occurrences](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-sensitive-data-occurrences.html) command and use the `finding-id` parameter to specify the unique identifier for the finding. For example:
```
C:\> aws macie2 get-sensitive-data-occurrences --finding-id "1f1c2d74db5d8caa76859ec52example"
```
Where *1f1c2d74db5d8caa76859ec52example* is the unique identifier for the finding. To obtain this identifier by using the AWS CLI, you can run the [list-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings.html) command.
If your request succeeds, Macie begins processing your request and you receive output similar to the following:
```
{
"status": "PROCESSING"
}
```
It can take several minutes to process your request. Within a few minutes, submit your request again.
If Macie can locate, retrieve, and encrypt the sensitive data samples, Macie returns the samples in a `sensitiveDataOccurrences` map. The map specifies 1–100 types of sensitive data reported by the finding and 1–10 samples for each type. Each sample contains the first 1–128 characters of an occurrence of sensitive data reported by the finding.
In the map, each key is the ID of the managed data identifier that detected the sensitive data, or the name and unique identifier for the custom data identifier that detected the sensitive data. The values are samples for the specified managed data identifier or custom data identifier. For example, the following response provides three samples of people's names and two samples of AWS secret access keys that were detected by managed data identifiers (`NAME` and `AWS_CREDENTIALS`, respectively).
```
{
"sensitiveDataOccurrences": {
"NAME": [
{
"value": "Akua Mansa"
},
{
"value": "John Doe"
},
{
"value": "Martha Rivera"
}
],
"AWS_CREDENTIALS": [
{
"value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
{
"value": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY"
}
]
},
"status": "SUCCESS"
}
```
If your request succeeds but sensitive data samples aren't available for the finding, you receive an `UnprocessableEntityException` message that indicates why samples aren't available. For example:
```
{
"message": "An error occurred (UnprocessableEntityException) when calling the GetSensitiveDataOccurrences operation: OBJECT_UNAVAILABLE"
}
```
In the preceding example, Macie attempted to retrieve samples from the affected S3 object but the object isn't available anymore. The contents of the object changed after Macie created the finding.
If your request succeeds but another type of error prevented Macie from retrieving and revealing sensitive data samples for the finding, you receive output similar to the following:
```
{
"error": "Macie can't retrieve the samples. You're not allowed to access the affected S3 object or the object is encrypted with a key that you're not allowed to use.",
"status": "ERROR"
}
```
The value for the `status` field is `ERROR` and the `error` field describes the error that occurred. The information in the [preceding topic](#findings-retrieve-sd-proc-criteria) can help you investigate the error.
------
# Schema for reporting the location of sensitive data
Amazon Macie uses standardized JSON structures to store information about where it finds sensitive data in Amazon Simple Storage Service (Amazon S3) objects. The structures are used by sensitive data findings and sensitive data discovery results. For sensitive data findings, the structures are part of the JSON schema for findings. To review the complete JSON schema for findings, see [Findings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) in the *Amazon Macie API Reference*. To learn more about sensitive data discovery results, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md).
**Topics**
+ [Schema overview](#findings-locate-sd-schema-overview)
+ [Schema details and examples](#findings-locate-sd-schema-examples)
## Schema overview
To report the location of sensitive data that Amazon Macie found in an affected S3 object, the JSON schema for sensitive data findings and sensitive data discovery results includes one `customDataIdentifiers` object and one `sensitiveData` object. The `customDataIdentifiers` object provides details about data that Macie detected using [custom data identifiers](custom-data-identifiers.md). The `sensitiveData` object provides details about data that Macie detected using [managed data identifiers](managed-data-identifiers.md).
Each `customDataIdentifiers` and `sensitiveData` object contains one or more `detections` arrays:
+ In a `customDataIdentifiers` object, the `detections` array indicates which custom data identifiers detected the data and produced the finding. For each custom data identifier, the array also indicates the number of occurrences of the data that the identifier detected. It can also indicate the location of the data that the identifier detected.
+ In a `sensitiveData` object, a `detections` array indicates the types of sensitive data that Macie detected using managed data identifiers. For each type of sensitive data, the array also indicates the number of occurrences of the data, and it can indicate the location of the data.
For a sensitive data finding, a `detections` array can include 1–15 `occurrences` objects. Each `occurrences` object specifies where Macie detected individual occurrences of a specific type of sensitive data.
For example, the following `detections` array indicates the location of three occurrences of sensitive data (US Social Security numbers) that Macie found in a CSV file.
```
"sensitiveData": [
{
"category": "PERSONAL_INFORMATION",
"detections": [
{
"count": 30,
"occurrences": {
"cells": [
{
"cellReference": null,
"column": 1,
"columnName": "SSN",
"row": 2
},
{
"cellReference": null,
"column": 1,
"columnName": "SSN",
"row": 3
},
{
"cellReference": null,
"column": 1,
"columnName": "SSN",
"row": 4
}
]
},
"type": "USA_SOCIAL_SECURITY_NUMBER"
}
```
The location and number of `occurrences` objects in a `detections` array varies based on the categories, types, and number of occurrences of sensitive data that Macie detects during an automated sensitive data discovery analysis cycle or a run of a sensitive data discovery job. For each analysis cycle or job run, Macie uses a *depth-first search* algorithm to populate the resulting findings with location data for 1–15 occurrences of sensitive data that Macie detects in S3 objects. These occurrences are indicative of the categories and types of sensitive data that an affected S3 bucket and object might contain.
An `occurrences` object can contain any the following structures, depending on an affected S3 object's file type or storage format:
+ `cells` array – This array applies to Microsoft Excel workbooks, CSV files, and TSV files. An object in this array specifies a cell or field that Macie detected an occurrence of sensitive data in.
+ `lineRanges` array – This array applies to email message (EML) files, and non-binary text files other than CSV, JSON, JSON Lines, and TSV files—for example, HTML, TXT, and XML files. An object in this array specifies a line or an inclusive range of lines that Macie detected an occurrence of sensitive data in, and the position of the data on the specified line or lines.
In certain cases, an object in a `lineRanges` array specifies the location of a sensitive data detection in a file type or storage format that's supported by another type of array. Those cases are: a detection in an unstructured section of an otherwise structured file, such as a comment in a file; a detection in a malformed file that Macie analyzes as plaintext; and, a CSV or TSV file that has one or more column names that Macie detected sensitive data in.
+ `offsetRanges` array – This array is reserved for future use. If this array is present, the value for it is null.
+ `pages` array – This array applies to Adobe Portable Document Format (PDF) files. An object in this array specifies a page that Macie detected an occurrence of sensitive data in.
+ `records` array – This array applies to Apache Avro object containers, Apache Parquet files, JSON files, and JSON Lines files. For Avro object containers and Parquet files, an object in this array specifies a record index and the path to a field in a record that Macie detected an occurrence of sensitive data in. For JSON and JSON Lines files, an object in this array specifies the path to a field or array that Macie detected an occurrence of sensitive data in. For JSON Lines files, it also specifies the index of the line that contains the data.
The contents of these arrays vary based on an affected S3 object's file type or storage format and its contents.
## Schema details and examples
Amazon Macie tailors the contents of the JSON structures that it uses to indicate where it detected sensitive data in specific types of files and content. The following topics explain and provide examples of these structures.
**Topics**
+ [Cells array](#findings-locate-sd-schema-examples-cell)
+ [LineRanges array](#findings-locate-sd-schema-examples-linerange)
+ [Pages array](#findings-locate-sd-schema-examples-page)
+ [Records array](#findings-locate-sd-schema-examples-record)
For a complete list of JSON structures that can be included in a sensitive data finding, see [Findings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) in the *Amazon Macie API Reference*.
### Cells array
**Applies to:** Microsoft Excel workbooks, CSV files, and TSV files
In a `cells` array, a `Cell` object specifies a cell or field that Macie detected an occurrence of sensitive data in. The following table describes the purpose of each field in a `Cell` object.
| Field | Type | Description |
| --- | --- | --- |
| cellReference | String | The location of the cell, as an absolute cell reference, that contains the occurrence. This field applies only to Excel workbooks. This value is null for CSV and TSV files. |
| column | Integer | The column number of the column that contains the occurrence. For an Excel workbook, this value correlates to the alphabetical character(s) for a column identifier—for example, 1 for column A, 2 for column B, and so on. |
| columnName | String | The name of the column that contains the occurrence, if available. |
| row | Integer | The row number of the row that contains the occurrence. |
The following example shows the structure of a `Cell` object that specifies the location of an occurrence of sensitive data that Macie detected in a CSV file.
```
"cells": [
{
"cellReference": null,
"column": 3,
"columnName": "SSN",
"row": 5
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the field in the fifth row of the third column (named *SSN*) of the file.
The following example shows the structure of a `Cell` object that specifies the location of an occurrence of sensitive data that Macie detected in an Excel workbook.
```
"cells": [
{
"cellReference": "Sheet2!C5",
"column": 3,
"columnName": "SSN",
"row": 5
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the worksheet named *Sheet2* in the workbook. In that worksheet, Macie detected sensitive data in the cell in the fifth row of the third column (column C, named *SSN*).
### LineRanges array
**Applies to:** Email message (EML) files, and non-binary text files other than CSV, JSON, JSON Lines, and TSV files—for example, HTML, TXT, and XML files
In a `lineRanges` array, a `Range` object specifies a line or an inclusive range of lines that Macie detected an occurrence of sensitive data in, and the position of the data on the specified line or lines.
This object is often empty for file types that are supported by other types of arrays in `occurrences` objects. Exceptions are:
+ Data in unstructured sections of an otherwise structured file, such as a comment in a file.
+ Data in a malformed file that Macie analyzes as plaintext.
+ A CSV or TSV file that has one or more column names that Macie detected sensitive data in.
The following table describes the purpose of each field in a `Range` object of a `lineRanges` array.
| Field | Type | Description |
| --- | --- | --- |
| end | Integer | The number of lines from the beginning of the file to the end of the occurrence. |
| start | Integer | The number of lines from the beginning of the file to the beginning of the occurrence. |
| startColumn | Integer | The number of characters, with spaces and starting from 1, from the beginning of the first line that contains the occurrence (start) to the beginning of the occurrence. |
The following example shows the structure of a `Range` object that specifies the location of an occurrence of sensitive data that Macie detected on a single line in a TXT file.
```
"lineRanges": [
{
"end": 1,
"start": 1,
"startColumn": 119
}
]
```
In the preceding example, the finding indicates that Macie detected a complete occurrence of sensitive data (a mailing address) in the first line of the file. The first character in the occurrence is 119 characters (with spaces) from the beginning of that line.
The following example shows the structure of a `Range` object that specifies the location of an occurrence of sensitive data that spans multiple lines in a TXT file.
```
"lineRanges": [
{
"end": 54,
"start": 51,
"startColumn": 1
}
]
```
In the preceding example, the finding indicates that Macie detected an occurrence of sensitive data (a mailing address) spanning lines 51 through 54 of the file. The first character in the occurrence is the first character on line 51 of the file.
### Pages array
**Applies to:** Adobe Portable Document Format (PDF) files
In a `pages` array, a `Page` object specifies a page that Macie detected an occurrence of sensitive data in. The object contains a `pageNumber` field. The `pageNumber` field stores an integer that specifies the page number of the page that contains the occurrence.
The following example shows the structure of a `Page` object that specifies the location of an occurrence of sensitive data that Macie detected in a PDF file.
```
"pages": [
{
"pageNumber": 10
}
]
```
In the preceding example, the finding indicates that page 10 of the file contains the occurrence.
### Records array
**Applies to:** Apache Avro object containers, Apache Parquet files, JSON files, and JSON Lines files
For an Avro object container or a Parquet file, a `Record` object in a `records` array specifies a record index and the path to a field in a record that Macie detected an occurrence of sensitive data in. For JSON and JSON Lines files, a `Record` object specifies the path to a field or array that Macie detected an occurrence of sensitive data in. For JSON Lines files, it also specifies the index of the line that contains the occurrence.
The following table describes the purpose of each field in a `Record` object.
| Field | Type | Description |
| --- | --- | --- |
| jsonPath | String | The path, as a JSONPath expression, to the occurrence. For an Avro object container or a Parquet file, this is the path to the field in the record (`recordIndex`) that contains the occurrence. For a JSON or JSON Lines file, this is the path to the field or array that contains the occurrence. If the data is a value in an array, the path also indicates which value contains the occurrence. If Macie detects sensitive data in the name of any element in the path, Macie omits the `jsonPath` field from a `Record` object. If the name of a path element exceeds 240 characters, Macie truncates the name by removing characters from the beginning of the name. If the resulting full path exceeds 250 characters, Macie also truncates the path, starting with the first element in the path, until the path contains 250 or fewer characters. |
| recordIndex | Integer | For an Avro object container or a Parquet file, the record index, starting from 0, for the record that contains the occurrence. For a JSON Lines file, the line index, starting from 0, for the line that contains the occurrence. This value is always 0 for JSON files. |
The following example shows the structure of a `Record` object that specifies the location of an occurrence of sensitive data that Macie detected in a Parquet file.
```
"records": [
{
"jsonPath": "$['abcdefghijklmnopqrstuvwxyz']",
"recordIndex": 7663
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the record of index 7663 (record number 7664). In that record, Macie detected sensitive data in the field named `abcdefghijklmnopqrstuvwxyz`. The full JSON path to the field in the record is `$.abcdefghijklmnopqrstuvwxyz`. The field is a direct descendant of the root (outer-level) object.
The following example also shows the structure of a `Record` object for an occurrence of sensitive data that Macie detected in a Parquet file. However, in this example, Macie truncated the name of the field that contains the occurrence because the name exceeds the character limit.
```
"records": [
{
"jsonPath": "$['...uvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz']",
"recordIndex": 7663
}
]
```
In the preceding example, the field is a direct descendant of the root (outer-level) object.
In the following example, also for an occurrence of sensitive data that Macie detected in a Parquet file, Macie truncated the full path to the field that contains the occurrence. The full path exceeds the character limit.
```
"records": [
{
"jsonPath": "$..usssn2.usssn3.usssn4.usssn5.usssn6.usssn7.usssn8.usssn9.usssn10.usssn11.usssn12.usssn13.usssn14.usssn15.usssn16.usssn17.usssn18.usssn19.usssn20.usssn21.usssn22.usssn23.usssn24.usssn25.usssn26.usssn27.usssn28.usssn29['abcdefghijklmnopqrstuvwxyz']",
"recordIndex": 2335
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the record of index 2335 (record number 2336). In that record, Macie detected sensitive data in the field named `abcdefghijklmnopqrstuvwxyz`. The full JSON path to the field in the record is:
`$['1234567890']usssn1.usssn2.usssn3.usssn4.usssn5.usssn6.usssn7.usssn8.usssn9.usssn10.usssn11.usssn12.usssn13.usssn14.usssn15.usssn16.usssn17.usssn18.usssn19.usssn20.usssn21.usssn22.usssn23.usssn24.usssn25.usssn26.usssn27.usssn28.usssn29['abcdefghijklmnopqrstuvwxyz']`
The following example shows the structure of a `Record` object that specifies the location of an occurrence of sensitive data that Macie detected in a JSON file. In this example, the occurrence is a specific value in an array.
```
"records": [
{
"jsonPath": "$.access.key[2]",
"recordIndex": 0
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the second value of an array named `key`. The array is a child of an object named `access`.
The following example shows the structure of a `Record` object that specifies the location of an occurrence of sensitive data that Macie detected in a JSON Lines file.
```
"records": [
{
"jsonPath": "$.access.key",
"recordIndex": 3
}
]
```
In the preceding example, the finding indicates that Macie detected sensitive data in the third value (line) in the file. In that line, the occurrence is in a field named `key`, which is a child of an object named `access`.