# Reviewing and analyzing Macie findings
<a name="findings"></a>

Amazon Macie generates findings when it detects potential policy violations or issues with the security or privacy of your Amazon Simple Storage Service (Amazon S3) general purpose buckets or it detects sensitive data in S3 objects. A *finding* is a detailed report of a potential issue or sensitive data that Macie found. Each finding provides a severity rating, information about the affected resource, and additional details, such as when and how Macie found the issue or data. Macie stores your policy and sensitive data findings for 90 days.

You can review, analyze, and manage findings in the following ways.

**Amazon Macie console**  
The **Findings** pages on the Amazon Macie console list your findings and provide detailed information for individual findings. These pages also provide options for grouping, filtering, and sorting findings, and for creating and managing suppression rules. Suppression rules can help you streamline your analysis of findings.

**Amazon Macie API**  
With the Amazon Macie API, you can query and retrieve findings data by using an AWS command line tool or an AWS SDK, or by sending HTTPS requests directly to Macie. To query the data, you submit a request to the Amazon Macie API and use supported parameters to specify which findings you want to retrieve. After you submit your request, Macie returns the results in a JSON response. You can then pass the results to another service or application for deeper analysis, long-term storage, or reporting. For more information, see the [Amazon Macie API Reference](https://docs.aws.amazon.com/macie/latest/APIReference/welcome.html).

**Amazon EventBridge**   
To further support integration with other services and systems, such as monitoring or event management systems, Macie publishes findings to Amazon EventBridge as events. EventBridge, formerly Amazon CloudWatch Events, is a serverless event bus service that can deliver a stream of real-time data from your own applications, software as a service (SaaS) applications, and AWS services such as Macie. It can route that data to targets such as AWS Lambda functions, Amazon Simple Notification Service topics, and Amazon Kinesis streams for additional, automated processing. Use of EventBridge also helps ensure longer-term retention of findings data. To learn more about EventBridge, see the [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html).  
Macie automatically publishes events to EventBridge for new findings. It also publishes events automatically for subsequent occurrences of existing policy findings. Because the findings data is structured as EventBridge events, you can more easily monitor, analyze, and act upon findings by using other services and tools. For example, you might use EventBridge to automatically send specific types of new findings to an AWS Lambda function that, in turn, processes and sends the data to your security incident and event management (SIEM) system. If you integrate AWS User Notifications with Macie, you can also use the events to be notified of findings automatically through delivery channels that you specify. To learn about using EventBridge events to monitor and process findings, see [Processing findings with Amazon EventBridge](findings-monitor-events-eventbridge.md).

**AWS Security Hub CSPM**   
For additional, broader analysis of your organization's security posture, you can also publish findings to AWS Security Hub CSPM. Security Hub CSPM is a service that collects security data from AWS services and supported AWS Partner Network security solutions to provide you with a comprehensive view of your security state across your AWS environment. Security Hub CSPM also helps you check your environment against security industry standards and best practices. To learn more about Security Hub CSPM, see the [AWS Security Hub User Guide](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html). To learn about using Security Hub CSPM to evaluate and process findings, see [Evaluating findings with AWS Security Hub CSPM](securityhub-integration.md).

In addition to findings, Macie creates sensitive data discovery results for S3 objects that it analyzes to discover sensitive data. A *sensitive data discovery result* is a record that logs details about the analysis of an object. This includes objects that Macie doesn't find sensitive data in, and therefore don't produce findings, and objects that Macie can't analyze due to errors or issues. Sensitive data discovery results provide you with analysis records that can be helpful for data privacy and protection audits or investigations. You can't access sensitive data discovery results directly on the Amazon Macie console or with the Amazon Macie API. Instead, you configure Macie to store the results in an S3 bucket. You can then optionally access and query the results in that bucket. To learn how to configure Macie to store the results, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md).

**Topics**
+ [Types of findings](findings-types.md)
+ [Severity scoring for findings](findings-severity.md)
+ [Working with sample findings](findings-samples.md)
+ [Reviewing findings](findings-view.md)
+ [Filtering findings](findings-filter-overview.md)
+ [Investigating sensitive data with findings](findings-investigate-sd.md)
+ [Suppressing findings](findings-suppression.md)

# Types of Macie findings
<a name="findings-types"></a>

Amazon Macie generates two categories of findings: *policy findings* and *sensitive data findings*. A *policy finding* is a detailed report of a potential policy violation or issue with the security or privacy of an Amazon Simple Storage Service (Amazon S3) general purpose bucket. Macie generates policy findings as part of its ongoing activities to evaluate and monitor your general purpose buckets for security and access control. A *sensitive data finding* is a detailed report of sensitive data that Macie detected in an S3 object. Macie generates sensitive data findings as part of the activities that it performs when you run sensitive data discovery jobs or it performs automated sensitive data discovery.

Within each category, there are specific types. A finding's type provides insight into the nature of the issue or sensitive data that Macie found. A finding's details provide a [severity rating](findings-severity.md), information about the affected resource, and additional information, such as when and how Macie found the issue or sensitive data. The severity and details of each finding vary depending on the type and nature of the finding.

**Topics**
+ [Types of policy findings](#findings-policy-types)
+ [Types of sensitive data findings](#findings-sensitive-data-types)

**Tip**  
To explore and learn about the different categories and types of findings that Macie can generate, [create sample findings](findings-samples.md). Sample findings use example data and placeholder values to demonstrate the kinds of information that each type of finding might contain.

## Types of policy findings
<a name="findings-policy-types"></a>

Amazon Macie generates a policy finding when the policies or settings for an S3 general purpose bucket are changed in a way that reduces the security or privacy of the bucket and the bucket's objects. For information about how Macie detects and evaluates these changes, see [How Macie monitors Amazon S3 data security](monitoring-s3-how-it-works.md).

Note that Macie generates a policy finding only if the change occurs after you enable Macie for your AWS account. For example, if block public access settings are disabled for an S3 bucket after you enable Macie, Macie generates a **Policy:IAMUser/S3BlockPublicAccessDisabled** finding for the bucket. If block public access settings were disabled for a bucket when you enabled Macie and they continue to be disabled, Macie doesn't generate a **Policy:IAMUser/S3BlockPublicAccessDisabled** finding for the bucket.

If Macie detects a subsequent occurrence of an existing policy finding, Macie updates the existing finding by adding details about the subsequent occurrence and incrementing the count of occurrences. Macie stores policy findings for 90 days.

Macie can generate the following types of policy findings for an S3 general purpose bucket.

**Policy:IAMUser/S3BlockPublicAccessDisabled**  
All bucket-level block public access settings were disabled for the bucket. Public access to the bucket is controlled by the block public access settings for the account, access control lists (ACLs), the bucket policy for the bucket, and other settings and policies that apply to the bucket.  
To investigate the finding, start by [reviewing the bucket’s details](monitoring-s3-inventory-review.md#monitoring-s3-inventory-view-details) in Macie. The details include a breakdown of the bucket's public access settings. For detailed information about the settings, see [Access control](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html) and [Blocking public access to your Amazon S3 storage](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html) in the *Amazon Simple Storage Service User Guide*.

**Policy:IAMUser/S3BucketEncryptionDisabled**  
Default encryption settings for the bucket were reset to default Amazon S3 encryption behavior, which is to encrypt new objects automatically with an Amazon S3 managed key.  
Starting January 5, 2023, Amazon S3 automatically applies server-side encryption with Amazon S3 managed keys (SSE-S3) as the base level of encryption for objects that are added to buckets. You can optionally configure a bucket's default encryption settings to instead use server-side encryption with an AWS KMS key (SSE-KMS) or dual-layer server-side encryption with an AWS KMS key (DSSE-KMS). If Macie generated this type of finding prior to January 5, 2023, the finding indicates that default encryption settings were disabled for the affected bucket. This meant that the bucket’s settings didn’t specify default server-side encryption behavior for new objects. The ability to disable default encryption settings for a bucket is no longer supported by Amazon S3.  
To learn about default encryption settings and options for S3 buckets, see [Setting default server-side encryption behavior for S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html) in the *Amazon Simple Storage Service User Guide*.

**Policy:IAMUser/S3BucketPublic**  
An ACL or bucket policy for the bucket was changed to allow access by anonymous users or all authenticated AWS Identity and Access Management (IAM) identities.  
To investigate the finding, start by [reviewing the bucket’s details](monitoring-s3-inventory-review.md#monitoring-s3-inventory-view-details) in Macie. The details include a breakdown of the bucket's public access settings. For detailed information about ACLs, bucket policies, and access settings for S3 buckets, see [Access control](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html) in the *Amazon Simple Storage Service User Guide*.

**Policy:IAMUser/S3BucketReplicatedExternally**  
Replication was enabled and configured to replicate objects from the bucket to a bucket for an AWS account that's external to (not part of) your organization. An *organization* is a set of Macie accounts that are centrally managed as a group of related accounts through AWS Organizations or by Macie invitation.  
Under certain conditions, Macie might generate this type of finding for a bucket that isn’t configured to replicate objects to a bucket for an external AWS account. This can occur if the destination bucket was created in a different AWS Region during the preceding 24 hours, after Macie retrieved bucket and object metadata from Amazon S3 as part of the [daily refresh cycle](monitoring-s3-how-it-works.md#monitoring-s3-how-it-works-data-refresh).  
To investigate the finding, start by refreshing your inventory data in Macie. Then [review the bucket’s details](monitoring-s3-inventory-review.md#monitoring-s3-inventory-view-details). The details indicate whether the bucket is configured to replicate objects to other buckets. If the bucket is configured to do this, the details include the account ID for each account that owns a destination bucket. For detailed information about replication settings for S3 buckets, see [Replicating objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html) in the *Amazon Simple Storage Service User Guide*.

**Policy:IAMUser/S3BucketSharedExternally**  
An ACL or bucket policy for the bucket was changed to allow the bucket to be shared with an AWS account that's external to (not part of) your organization. An *organization* is a set of Macie accounts that are centrally managed as a group of related accounts through AWS Organizations or by Macie invitation.  
In certain cases, Macie might generate this type of finding for a bucket that isn’t shared with an external AWS account. This can occur if Macie isn’t able to fully evaluate the relationship between the `Principal` element in the bucket’s policy and certain [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) or [Amazon S3 condition keys](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html#amazons3-policy-keys) in the `Condition` element of the policy. This can be the case for the following condition keys: `aws:PrincipalAccount`, `aws:PrincipalArn`, `aws:PrincipalOrgID`, `aws:PrincipalOrgPaths`, `aws:PrincipalTag`, `aws:PrincipalType`, `aws:SourceAccount`, `aws:SourceArn`, `aws:SourceIp`, `aws:SourceOrgID`, `aws:SourceOrgPaths`, `aws:SourceVpc`, `aws:SourceVpce`, `aws:userid`, `s3:DataAccessPointAccount`, and `s3:DataAccessPointArn`. We recommend that you review the bucket’s policy to determine whether this access is intended and safe.  
To learn about ACLs and bucket policies for S3 buckets, see [Access control](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html) in the *Amazon Simple Storage Service User Guide*.

**Policy:IAMUser/S3BucketSharedWithCloudFront**  
The bucket policy for the bucket was changed to allow the bucket to be shared with an Amazon CloudFront origin access identity (OAI), a CloudFront origin access control (OAC), or both a CloudFront OAI and a CloudFront OAC. A CloudFront OAI or OAC allows users to access a bucket's objects through one or more specified CloudFront distributions.  
To learn about CloudFront OAIs and OACs, see [Restricting access to an Amazon S3 origin](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) in the *Amazon CloudFront Developer Guide*.

**Note**  
In certain cases, Macie generates a **Policy:IAMUser/S3BucketSharedExternally** finding instead of a **Policy:IAMUser/S3BucketSharedWithCloudFront** finding for a bucket. These cases are:  
The bucket is shared with an AWS account that's external to your organization, in addition to a CloudFront OAI or OAC.
The bucket's policy specifies a canonical user ID, instead of the Amazon Resource Name (ARN), of a CloudFront OAI.
This produces a higher severity policy finding for the bucket.

## Types of sensitive data findings
<a name="findings-sensitive-data-types"></a>

Amazon Macie generates a sensitive data finding when it detects sensitive data in an S3 object that it analyzes to discover sensitive data. This includes analysis that Macie performs when you run a sensitive data discovery job or it performs automated sensitive data discovery.

For example, if you create and run a sensitive data discovery job and Macie detects bank account numbers in an S3 object, Macie generates a **SensitiveData:S3Object/Financial** finding for the object. Similarly, if Macie detects bank account numbers in an S3 object that it analyzes during an automated sensitive data discovery cycle, Macie generates a **SensitiveData:S3Object/Financial** finding for the object.

If Macie detects sensitive data in the same S3 object during a subsequent job run or automated sensitive data discovery cycle, Macie generates a new sensitive data finding for the object. Unlike policy findings, all sensitive data findings are treated as new (unique). Macie stores sensitive data findings for 90 days.

Macie can generate the following types of sensitive data findings for an S3 object.

**SensitiveData:S3Object/Credentials**  
The object contains sensitive credentials data, such as AWS secret access keys or private keys.

**SensitiveData:S3Object/CustomIdentifier**  
The object contains text that matches the detection criteria of one or more custom data identifiers. The object might contain more than one type of sensitive data.

**SensitiveData:S3Object/Financial**  
The object contains sensitive financial information, such as bank account numbers or credit card numbers.

**SensitiveData:S3Object/Multiple**  
The object contains more than one category of sensitive data—any combination of credentials data, financial information, personal information, or text that matches the detection criteria of one or more custom data identifiers.

**SensitiveData:S3Object/Personal**  
The object contains sensitive personal information—personally identifiable information (PII) such as passport numbers or driver's license identification numbers, personal health information (PHI) such as health insurance or medical identification numbers, or a combination of PII and PHI.

For information about the types of sensitive data that Macie can detect using built-in criteria and techniques, see [Using managed data identifiers](managed-data-identifiers.md). For information about the types of S3 objects that Macie can analyze, see [Supported storage classes and formats](discovery-supported-storage.md).

# Severity scoring for Macie findings
<a name="findings-severity"></a>

When Amazon Macie generates a policy or sensitive data finding, it automatically assigns a severity to the finding. A finding's severity reflects the principal characteristics of the finding, which can help you assess and prioritize the finding. A finding's severity doesn't imply or otherwise indicate the criticality or importance that an affected resource might have for your organization.

For policy findings, severity is based on the nature of a potential issue with the security or privacy of an Amazon Simple Storage Service (Amazon S3) general purpose bucket. For sensitive data findings, severity is based on the nature and number of occurrences of sensitive data that Macie detected in an S3 object. 

In Macie, a finding's severity is represented in two ways.

**Severity level**  
This is a qualitative representation of severity. Severity levels range from *Low*, for least severe, to *High*, for most severe.  
Severity levels appear directly on the Amazon Macie console. They're also available in JSON representations of findings on the Macie console, from the Amazon Macie API, and in sensitive data discovery results that correlate to sensitive data findings. Severity levels are also included in finding events that Macie publishes to Amazon EventBridge and findings that Macie publishes to AWS Security Hub CSPM.

**Severity score**  
This is a numerical representation of severity. Severity scores range from *1* through *3* and map directly to severity levels:      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/macie/latest/user/findings-severity.html)
Severity scores don't appear directly on the Amazon Macie console. However, they're available in JSON representations of findings on the Macie console, from the Amazon Macie API, and in sensitive data discovery results that correlate to sensitive data findings. Severity scores are also included in finding events that Macie publishes to Amazon EventBridge. They aren't included in findings that Macie publishes to AWS Security Hub CSPM.

The topics in this section indicate how Macie determines the severity of policy findings and sensitive data findings.

**Topics**
+ [Severity scoring for policy findings](#findings-severity-policy)
+ [Severity scoring for sensitive data findings](#findings-severity-mdis)

## Severity scoring for policy findings
<a name="findings-severity-policy"></a>

The severity of a policy finding is based on the nature of a potential issue with the security or privacy of an S3 general purpose bucket. The following table lists the severity levels that Amazon Macie assigns to each type of policy finding. For a description of each type, see [Types of findings](findings-types.md).


| Finding type | Severity level | 
| --- | --- | 
| Policy:IAMUser/S3BlockPublicAccessDisabled | High | 
|  Policy:IAMUser/S3BucketEncryptionDisabled  | Low | 
| Policy:IAMUser/S3BucketPublic | High | 
| Policy:IAMUser/S3BucketReplicatedExternally | High | 
| Policy:IAMUser/S3BucketSharedExternally | High | 
| Policy:IAMUser/S3BucketSharedWithCloudFront | Medium | 

The severity of a policy finding doesn't change based on the number of occurrences of the finding. 

## Severity scoring for sensitive data findings
<a name="findings-severity-mdis"></a>

The severity of a sensitive data finding is based on the nature and number of occurrences of sensitive data that Amazon Macie detected in an S3 object. The following topics indicate how Macie determines the severity of each type of sensitive data finding:
+ [SensitiveData:S3Object/Credentials](#findings-severity-credentials)
+ [SensitiveData:S3Object/CustomIdentifier](#findings-severity-cdis)
+ [SensitiveData:S3Object/Financial](#findings-severity-financial)
+ [SensitiveData:S3Object/Personal](#findings-severity-personal)
+ [SensitiveData:S3Object/Multiple](#findings-severity-multiple)

For details about the types of sensitive data that Macie can detect and report in sensitive data findings, see [Using managed data identifiers](managed-data-identifiers.md) and [Building custom data identifiers](custom-data-identifiers.md).

### SensitiveData:S3Object/Credentials
<a name="findings-severity-credentials"></a>

A **SensitiveData:S3Object/Credentials** finding indicates that Macie detected sensitive credentials data in an S3 object. For this type of finding, Macie determines severity based on the type and number of occurrences of the credentials data that Macie detected in the object.

The following table indicates the severity levels that Macie assigns to findings that report occurrences of credentials data in an S3 object.


| Sensitive data type | 1 occurrence | 2–99 occurrences | 100 or more occurrences | 
| --- | --- | --- | --- | 
| AWS secret access key | High | High | High | 
| Google Cloud API key | High | High | High | 
| HTTP Basic Authorization header | High | High | High | 
| JSON Web Token (JWT) | High | High | High | 
| OpenSSH private key | High | High | High | 
| PGP private key | High | High | High | 
| Public-Key Cryptography Standard (PKCS) private key | High | High | High | 
| PuTTY private key | High | High | High | 
| Stripe API key | High | High | High | 

### SensitiveData:S3Object/CustomIdentifier
<a name="findings-severity-cdis"></a>

A **SensitiveData:S3Object/CustomIdentifier** finding indicates that an S3 object contains text that matches the detection criteria of one or more custom data identifiers. The object might contain more than one type of sensitive data.

By default, Macie assigns the **Medium** severity level to this type of finding. If the affected S3 object contains at least one occurrence of text that matches the detection criteria of at least one custom data identifier, Macie automatically assigns the **Medium** severity level to the finding. The severity of the finding doesn't change based on the number of occurrences of text that match a custom data identifier's criteria.

However, the severity of this type of finding can vary if you defined custom severity settings for a custom data identifier that produced the finding. If this is the case, Macie determines severity as follows:
+ If the S3 object contains text that matches the detection criteria of only one custom data identifier, Macie determines the finding's severity based on the severity settings for that identifier.
+ If the S3 object contains text that matches the detection criteria of more than one custom data identifier, Macie determines the finding's severity by evaluating the severity settings for each custom data identifier, determining which of those settings produces the highest severity, and then assigning that highest severity to the finding.

To review the severity settings for a custom data identifier, you can use the Amazon Macie console or the Amazon Macie API. To review the settings on the console, choose **Custom data identifiers** in the navigation pane, and then choose the name of the custom data identifier. The **Severity** section shows the settings. To retrieve the settings programmatically, use the [GetCustomDataIdentifier](https://docs.aws.amazon.com/macie/latest/APIReference/custom-data-identifiers-id.html) operation or, if you're using the AWS Command Line Interface, run the [get-custom-data-identifier](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-custom-data-identifier.html) command. To learn about the settings, see [Configuration options for custom data identifiers](cdis-options.md).

### SensitiveData:S3Object/Financial
<a name="findings-severity-financial"></a>

A **SensitiveData:S3Object/Financial** finding indicates that Macie detected sensitive financial information in an S3 object. For this type of finding, Macie determines severity based on the type and number of occurrences of the financial information that Macie detected in the object.

The following table indicates the severity levels that Macie assigns to findings that report occurrences of financial information in an S3 object.


| Sensitive data type | 1 occurrence | 2–99 occurrences | 100 or more occurrences | 
| --- | --- | --- | --- | 
|  Bank account number 1  | High | High | High | 
|  Credit card expiration date  | Low | Medium | High | 
|  Credit card magnetic stripe data  | High | High | High | 
|  Credit card number 2  | High | High | High | 
|  Credit card verification code  | Medium | High | High | 

1. Severity levels are the same for any type of bank account number—a Basic Bank Account Number (BBAN), an International Bank Account Number (IBAN), or a Canadian or US bank account number.

1. Severity levels are the same for credit card numbers that are or aren't in proximity of a keyword.

If a finding reports multiple types of financial information in an S3 object, Macie determines the finding's severity by calculating the severity for each type of financial information that Macie detected, determining which type produces the highest severity, and assigning that highest severity to the finding. For example, if Macie detects 10 credit card expiration dates (**Medium** severity level) and 10 credit card numbers (**High** severity level) in an object, Macie assigns the **High** severity level to the finding.

### SensitiveData:S3Object/Personal
<a name="findings-severity-personal"></a>

A **SensitiveData:S3Object/Personal** finding indicates that Macie detected sensitive personal information in an S3 object. The information can be personal health information (PHI), personally identifiable information (PII), or a combination of the two. For this type of finding, Macie determines severity based on the type and number of occurrences of the personal information that Macie detected in the object.

The following table indicates the severity levels that Macie assigns to sensitive data findings that report occurrences of PHI in an S3 object.


| Sensitive data type | 1 occurrence | 2–99 occurrences | 100 or more occurrences | 
| --- | --- | --- | --- | 
|  Drug Enforcement Agency (DEA) Registration Number  | High | High | High | 
| Health Insurance Claim Number (HICN) | High | High | High | 
| Health insurance or medical identification number | High | High | High | 
| Healthcare Common Procedure Coding System (HCPCS) code | High | High | High | 
| National Drug Code (NDC) | High | High | High | 
| National Provider Identifier (NPI) | High | High | High | 
| Unique device identifier (UDI) | Low | Medium | High | 

The following table indicates the severity levels that Macie assigns to sensitive data findings that report occurrences of PII in an S3 object.


| Sensitive data type | 1 occurrence | 2–99 occurrences | 100 or more occurrences | 
| --- | --- | --- | --- | 
|  Birth date  | Low | Medium | High | 
| Driver’s license identification number | Low | Medium | High | 
| Electoral roll number | High | High | High | 
| Full name | Low | Medium | High | 
| Global Positioning System (GPS) coordinates | Low | Medium | Medium | 
| HTTP cookie | Low | Medium | High | 
| Mailing address | Low | Medium | High | 
| National identification number | High | High | High | 
| National Insurance Number (NINO) | High | High | High | 
| Passport number | Medium | High | High | 
| Permanent residence number | High | High | High | 
| Phone number | Low | Medium | High | 
| Public transportation card number | Medium | Medium | High | 
| Social Insurance Number (SIN) | High | High | High | 
| Social Security number (SSN) | High | High | High | 
|  Taxpayer identification or reference number \$1  | High | High | High | 
|  Vehicle identification number (VIN)  | Low | Low | Medium | 

\$1 Exceptions are: CUIT numbers for organizations in Argentina (`ARGENTINA_ORGANIZATION_TAX_IDENTIFICATION_NUMBER`), NIT numbers for organizations in Colombia (`COLOMBIA_ORGANIZATION_NIT_NUMBER`), and RFC numbers for organizations in Mexico (`MEXICO_ORGANIZATION_RFC_NUMBER`). For those types, the severity levels are: **Medium** for 1–99 occurrences, and **High** for 100 or more occurrences.

If a finding reports multiple types of PHI, PII, or both PHI and PII in an object, Macie determines the finding's severity by calculating the severity for each type, determining which type produces the highest severity, and assigning that highest severity to the finding.

For example, if Macie detects 10 full names (**Medium** severity level) and 5 passport numbers (**High** severity level) in an object, Macie assigns the **High** severity level to the finding. Similarly, if Macie detects 10 full names (**Medium** severity level) and 10 health insurance identification numbers (**High** severity level) in an object, Macie assigns the **High** severity level to the finding.

### SensitiveData:S3Object/Multiple
<a name="findings-severity-multiple"></a>

A **SensitiveData:S3Object/Multiple** finding indicates that Macie detected multiple categories of sensitive data in an S3 object. The sensitive data can be any combination of credentials data, financial information, personal information, or text that matches the detection criteria of one or more custom data identifiers.

For this type of finding, Macie determines severity by calculating the severity for each type of sensitive data that Macie detected (as indicated in the preceding topics), determining which type produces the highest severity, and assigning that highest severity to the finding.

For example, if Macie detects 10 full names (**Medium** severity level) and 10 AWS secret access keys (**High** severity level) in an object, Macie assigns the **High** severity level to the finding.

# Working with Macie sample findings
<a name="findings-samples"></a>

To explore and learn about the different [types of findings](findings-types.md) that Amazon Macie can generate, you can create sample findings. Sample findings use example data and placeholder values to demonstrate the kinds of information that each type of finding might contain.

For example, the **Policy:IAMUser/S3BucketPublic** sample finding contains details about a fictitious Amazon Simple Storage Service (Amazon S3) bucket. The finding's details include example data about an actor and action that changed the access control list (ACL) for the bucket and made the bucket publicly accessible. Similarly, the **SensitiveData:S3Object/Multiple** sample finding contains details about a fictitious Microsoft Excel workbook. The finding's details include example data about the types and location of sensitive data in the workbook.

In addition to familiarizing yourself with the information that different types of findings might contain, you can use sample findings to test integration with other applications, services, and systems. Depending on the [suppression rules](findings-suppression.md) for your account, Macie can publish sample findings to Amazon EventBridge as events. The example data in these events can help you develop and test automated solutions for monitoring and processing findings with EventBridge. Depending on the [publication settings](findings-publish-frequency.md) for your account, Macie can also publish sample findings to AWS Security Hub CSPM. This means that you can also use sample findings to develop and test solutions for evaluating Macie findings with Security Hub CSPM. For information about publishing findings to these services, see [Monitoring and processing findings](findings-monitor.md).

**Topics**
+ [Creating sample findings](#findings-samples-create)
+ [Reviewing sample findings](#findings-samples-review)
+ [Suppressing sample findings](#findings-samples-suppress)

## Creating sample findings
<a name="findings-samples-create"></a>

You can create sample findings by using the Amazon Macie console or the Amazon Macie API. If you use the console, Macie automatically generates one sample finding for each type of finding that Macie supports. If you use the API, you can create a sample for each type, or only certain types that you specify.

------
#### [ Console ]

Follow these steps to create sample findings by using the Amazon Macie console.

**To create sample findings**

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 **Settings**.

1. Under **Sample findings**, choose **Generate sample findings**.

------
#### [ API ]

To create sample findings programmatically, use the [CreateSampleFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-sample.html) operation of the Amazon Macie API. When you submit your request, optionally use the `findingTypes` parameter to specify only certain types of sample findings to create. To automatically create samples of all types, don't include this parameter in your request. 

To create sample findings by using the AWS Command Line Interface (AWS CLI), run the [create-sample-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/create-sample-findings.html) command. To automatically create samples of all types of findings, don't include the `finding-types` parameter. To create samples of only certain types of findings, include this parameter and specify the types of sample findings to create. For example:

```
C:\> aws macie2 create-sample-findings --finding-types "SensitiveData:S3Object/Multiple" "Policy:IAMUser/S3BucketPublic"
```

Where *SensitiveData:S3Object/Multiple* is a type of sensitive data finding to create and *Policy:IAMUser/S3BucketPublic* is a type of policy finding to create.

If the command runs successfully, Macie returns an empty response.

------

If you create sample findings again within 90 days, Macie generates a new finding for each type of sensitive data finding that you create. For policy findings, Macie updates each existing sample finding by incrementing the count of occurrences and updating details about when the subsequent occurrence occurred.

## Reviewing sample findings
<a name="findings-samples-review"></a>

To help you identify sample findings, Amazon Macie sets the value for the **Sample** field of each sample finding to *True*. In addition, the name of the affected S3 bucket is the same for all sample findings: *macie-sample-finding-bucket*. If you review sample findings by using **Findings** pages on the Amazon Macie console, Macie also displays the **[SAMPLE]** prefix in the **Finding type** field for each sample finding.

------
#### [ Console ]

Follow these steps to review sample findings by using the Amazon Macie console.

**To review sample findings**

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, do any of the following:
   + In the **Finding type** column, locate findings whose type begins with **[SAMPLE]**, as shown in the following image.  
![\[The Finding type column on the Findings page. It lists findings that have the [SAMPLE] prefix.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-samples-all.png)
   + By using the **Filter criteria** box above the table, filter the table to display only sample findings. To do this, place your cursor in the box. In the list of fields that appears, choose **Sample**. Then choose **True**, and then choose **Apply**.

1. To review the details of a specific sample finding, choose the finding. The details panel displays information for the finding.

You can also download and save the details of one or more sample findings as a JSON file. To do this, select the checkbox for each sample finding that you want to download and save. Then choose **Export (JSON)** on the **Actions** menu at the top of the **Findings** page. In the window that appears, choose **Download**. For detailed descriptions of the JSON fields that a finding can include, see [Findings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) in the *Amazon Macie API Reference*.

------
#### [ API ]

To review sample findings programmatically, first use the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) operation of the Amazon Macie API to retrieve the unique identifier (`findingId`) for each sample finding that you created. Then use the [GetFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) operation to retrieve the details of those findings.

When you submit the **ListFindings** request, you can specify filter criteria to include only sample findings in the results. To do this, add a filter condition where the value for the `sample` field is `true`. If you're using the AWS CLI, run the [list-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings.html) command and use the `finding-criteria` parameter to specify the filter condition. For example:

```
C:\> aws macie2 list-findings --finding-criteria={\"criterion\":{\"sample\":{\"eq\":[\"true\"]}}}
```

If your request succeeds, Macie returns a `findingIds` array. The array lists the unique identifier for each sample finding for your account in the current AWS Region.

To then retrieve the details of the sample findings, specify these unique identifiers in a **GetFindings** request or, for the AWS CLI, when you run the [get-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/get-findings.html) command.

------

## Suppressing sample findings
<a name="findings-samples-suppress"></a>

Like other findings, Amazon Macie stores sample findings for 90 days. After you finish reviewing and experimenting with the samples, you can optionally archive them by [creating a suppression rule](findings-suppression-rule-create.md). If you do this, the sample findings stop appearing by default on the console and their status changes to *archived*.

To archive sample findings by using the Amazon Macie console, configure the rule to archive findings where the value for the **Sample** field is **True**. To archive sample findings by using the Amazon Macie API, configure the rule to archive findings where the value for the `sample` field is `true`.

# Reviewing Macie findings by using the console
<a name="findings-view"></a>

Amazon Macie monitors your AWS environment and generates policy findings when it detects potential policy violations or issues with the security or privacy of your Amazon Simple Storage Service (Amazon S3) general purpose buckets. Macie generates sensitive data findings when it detects sensitive data in S3 objects. Macie stores your policy and sensitive data findings for 90 days.

Each finding specifies a [finding type](findings-types.md) and [severity rating](findings-severity.md). Additional details include information about the affected resource and when and how Macie found the issue or sensitive data reported by the finding. The severity and details of each finding vary depending on the type and nature of the finding.

By using the Amazon Macie console, you can review and analyze findings, and access the details of individual findings. You can also export one or more findings to a JSON file. To streamline your analysis, the console offers several options that can help you build custom views of findings.

**Use predefined groupings**  
Use specific pages to review findings that are grouped by criteria such as affected S3 bucket, finding type, or sensitive data discovery job. With these pages, you can review aggregated statistics for each group, such as the count of findings by severity. You can also drill down to review the details of individual findings in a group, and you can apply filters to refine your analysis.  
For example, if you group all findings by S3 bucket and note that a particular bucket has a policy violation, you can quickly determine whether there are also sensitive data findings for the bucket. To do this, choose **By bucket** in the navigation pane (under **Findings**), and then choose the bucket. In the details panel that appears, the **Findings by type** section lists the types of findings that apply to the bucket, as shown in the following image.  

![\[The details panel for a bucket on the Findings by bucket page.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-group-bucket.png)

To investigate a specific type, choose the number for the type. Macie displays a table of all the findings that match the selected type and apply to the S3 bucket. To refine the results, filter the table.

**Create and apply filters**  
Use specific finding attributes to include or exclude certain findings from a **Findings** table. A *finding attribute* is a field that stores specific data for a finding, such as finding type, severity, or the name of the affected S3 bucket. If you filter a table, you can more easily identify findings that have specific characteristics. Then you can drill down to review the details of those findings.  
For example, to review all of your sensitive data findings, add filter criteria for the **Category** field. To refine the results and include only a specific type of sensitive data finding, add filter criteria for the **Finding type** field. For example:   

![\[The Filter criteria box, on the Findings page, with filter tokens for two conditions.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-sd-example.png)

To then review the details of a particular finding, choose the finding. The details panel displays information for the finding.

You can also sort findings in ascending or descending order by certain fields. To do this, choose the column heading for the field. To change the sort order, choose the column heading again.

**To review findings by using the console**

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**. The **Findings** page displays findings that Macie created or updated for your account in the current AWS Region during the past 90 days. By default, this doesn't include findings that were suppressed by a [suppression rule](findings-suppression.md).

1. To pivot on and review findings by a predefined logical group, choose **By bucket**, **By type**, or **By job** in the navigation pane (under **Findings**). Then choose an item in the table. In the details panel, choose the link for the field to pivot on.

1. To filter the findings by specific criteria, use the filter options above the table:
   + To display findings that were suppressed by a suppression rule, use the **Finding status** menu. Choose **All** to display both suppressed and unsuppressed findings, or choose **Archived** to display only suppressed findings. To then hide suppressed findings again, choose **Current**.
   + To display only those findings that have a specific attribute, use the **Filter criteria** box. Place your cursor in the box and add a filter condition for the attribute. To further refine the results, add conditions for additional attributes. To then remove a condition, choose the remove condition icon (![\[The remove filter condition icon, which is a circle that has an X in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-filter-remove.png)) for the condition to remove.

   For more information about filtering findings, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).

1. To sort the findings by a specific field, choose the column heading for the field. To change the sort order, choose the column heading again.

1. To review the details of a specific finding, choose the finding. The details panel displays information for the finding.
**Tips**  
In the details panel, you can pivot and drill down on certain fields. To show findings that have the same value for a field, choose ![\[The zoom in icon, which is a magnifying glass that has a plus sign in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-magnifying-glass-plus-sign.png) in the field. Choose ![\[The zoom out icon, which is a magnifying glass that has a minus sign in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-magnifying-glass-minus-sign.png) to show findings that have other values for the field.  
For a sensitive data finding, you can also use the details panel to investigate sensitive data that Macie found in the affected S3 object:  
To locate occurrences of a specific type of sensitive data, choose the numeric link in the field for that type of data. Macie displays information (in JSON format) about where Macie found the data. For more information, see [Locating sensitive data](findings-locate-sd.md).
To retrieve samples of the sensitive data that Macie found, choose **Review** in the **Reveal samples** field. For more information, see [Retrieving sensitive data samples](findings-retrieve-sd.md).
To navigate to the corresponding sensitive data discovery result, choose the link in the **Detailed result location** field. Macie opens the Amazon S3 console and displays the file or folder that contains the discovery result. For more information, see [Storing and retaining sensitive data discovery results](discovery-results-repository-s3.md).

1. To download and save the details of one or more findings as a JSON file, select the checkbox for each finding to download and save. Then choose **Export (JSON)** on the **Actions** menu. In the window that appears, choose **Download**. For detailed descriptions of the JSON fields that a finding can include, see [Findings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) in the *Amazon Macie API Reference*.

In certain cases, a finding might not include all the details of an affected S3 bucket. This can occur if you store more than 10,000 buckets in Amazon S3. Macie maintains complete inventory data for only 10,000 buckets for an account—the 10,000 buckets that were most recently created or changed. To review additional details for an affected bucket, you can use data in the finding to determine the bucket's name, the account ID for the AWS account that owns the bucket, and the AWS Region that stores the bucket. You can then use Amazon S3 to review all the bucket's details.

# Filtering Macie findings
<a name="findings-filter-overview"></a>

To perform targeted analysis and to analyze findings more efficiently, you can filter Amazon Macie findings. With filters, you build custom views and queries for findings, which can help you identify and focus on findings that have specific characteristics. Use the Amazon Macie console to filter findings, or submit queries programmatically using the Amazon Macie API.

When you create a filter, you use specific attributes of findings to define criteria for including or excluding findings from a view or from query results. A *finding attribute* is a field that stores specific data for a finding, such as severity, type, or the name of the S3 bucket that a finding applies to.

In Macie, a filter consists of one or more conditions. Each condition, also referred to as a *criterion*, consists of three parts:
+ An attribute-based field, such as **Severity** or **Finding type**.
+ An operator, such as *equals* or *not equals*.
+ One or more values. The type and number of values depends on the field and operator that you choose.

If you create a filter that you want to use again, you can save it as a *filter rule*. A *filter rule* is a set of filter criteria that you create and save to reapply when you review findings on the Amazon Macie console.

You can also save a filter as a *suppression rule*. A *suppression rule* is a set of filter criteria that you create and save to automatically archive findings that match the criteria of the rule. To learn about suppression rules, see [Suppressing findings](findings-suppression.md).

**Topics**
+ [Filter fundamentals](findings-filter-basics.md)
+ [Fields for filtering findings](findings-filter-fields.md)
+ [Creating and applying filters](findings-filter-procedure.md)
+ [Defining filter rules](findings-filter-rule-procedures.md)

# Fundamentals of filtering Macie findings
<a name="findings-filter-basics"></a>

When you filter findings, keep the following features and guidelines in mind. Also note that filtered results are limited to the preceding 90 days and the current AWS Region. Amazon Macie stores your findings for only 90 days in each AWS Region.

**Topics**
+ [Using multiple conditions in a filter](#findings-filter-basics-multiple-criteria)
+ [Specifying values for fields](#findings-filter-basics-value-types)
+ [Specifying multiple values for a field](#findings-filter-basics-multiple-values)
+ [Using operators in conditions](#findings-filter-basics-operators)

## Using multiple conditions in a filter
<a name="findings-filter-basics-multiple-criteria"></a>

A filter can include one or more conditions. Each condition, also referred to as a *criterion*, consists of three parts: 
+ An attribute-based field, such as **Severity** or **Finding type**. For a list of fields that you can use, see [Fields for filtering Macie findings](findings-filter-fields.md).
+ An operator, such as *equals* or *not equals*. For a list of operators that you can use, see [Using operators in conditions](#findings-filter-basics-operators).
+ One or more values. The type and number of values depends on the field and operator that you choose.

If a filter contains multiple conditions, Amazon Macie uses AND logic to join the conditions and evaluate the filter criteria. This means that a finding matches the filter criteria only if it matches *all* the conditions in the filter.

For example, if you add a condition to include only high-severity findings and add another condition to include only sensitive data findings, Macie returns all high-severity, sensitive data findings. In other words, Macie excludes all policy findings and all medium-severity and low-severity sensitive data findings.

You can use a field only once in a filter. However, you can specify multiple values for many fields.

For example, if a condition uses the **Severity** field to include only high-severity findings, you can’t use the **Severity** field in another condition to include medium-severity or low-severity findings. Instead, specify multiple values for the existing condition, or use a different operator for the existing condition. For example, to include all medium-severity and high-severity findings, add a **Severity** *equals* *Medium, High* condition or add a **Severity** *not equals* *Low* condition.

## Specifying values for fields
<a name="findings-filter-basics-value-types"></a>

When you specify a value for a field, the value has to conform to the underlying data type for the field. Depending on the field, you can specify one of the following types of values.

**Array of text (strings)**  
Specifies a list of text (string) values for a field. Each string correlates to a predefined or existing value for a field—for example, *High* for the **Severity** field, *SensitiveData:S3Object/Financial* for the **Finding type** field, or the name of an S3 bucket for the **S3 bucket name** field.  
If you use an array, note the following:  
+ Values are case sensitive.
+ You can’t specify partial values or use wildcard characters in values. You have to specify a complete, valid value for the field. 
For example, to filter findings for an S3 bucket named *my-S3-bucket*, enter **my-S3-bucket** as the value for the **S3 bucket name** field. If you enter any other value, such as **my-s3-bucket** or **my-S3**, Macie won’t return findings for the bucket.  
For a list of valid values for each field, see [Fields for filtering Macie findings](findings-filter-fields.md).  
You can specify as many as 50 values in an array. How you specify the values depends on whether you use the Amazon Macie console or the Amazon Macie API, as discussed in [Specifying multiple values for a field](#findings-filter-basics-multiple-values). 

**Boolean**  
Specifies one of two mutually exclusive values for a field.  
If you use the Amazon Macie console to specify this type of value, the console provides a list of values to choose from. If you use the Amazon Macie API, specify `true` or `false` for the value.

**Date/Time (and time ranges)**  
Specifies an absolute date and time for a field. If you specify this type of value, you have to specify both a date and time.  
On the Amazon Macie console, date and time values are in your local time zone and use 24-hour notation. In all other contexts, these values are in Coordinated Universal Time (UTC) and extended ISO 8601 format—for example `2020-09-01T14:31:13Z` for 2:31:13 PM UTC September 1, 2020.  
If a field stores a date/time value, you can use the field to define a fixed or relative time range. For example, you can include only those findings that were created between two specific dates and times, or only those findings that were created before or after a specific date and time. How you define a time range depends on whether you use the Amazon Macie console or the Amazon Macie API:  
+ On the console, use a date picker or enter text directly in the **From** and **To** boxes. 
+ With the API, define a fixed time range by adding a condition that specifies the first date and time in the range, and add another condition that specifies the last date and time in the range. If you do this, Macie uses AND logic to join the conditions. To define a relative time range, add one condition that specifies the first or last date and time in the range. Specify the values as Unix timestamps in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.
On the console, time ranges are inclusive. With the API, time ranges can be inclusive or exclusive, depending on the operator that you choose.

**Number (and numeric ranges)**  
Specifies a long integer for a field.  
If a field stores a numeric value, you can use the field to define a fixed or relative numeric range. For example, you can include only those findings that report 50-90 occurrences of sensitive data in an S3 object. How you define a numeric range depends on whether you use the Amazon Macie console or the Amazon Macie API:  
+ On the console, use the **From** and **To** boxes to enter the lowest and highest numbers in the range, respectively.
+ With the API, define a fixed numeric range by adding a condition that specifies the lowest number in the range, and add another condition that specifies the highest number in the range. If you do this, Macie uses AND logic to join the conditions. To define a relative numeric range, add one condition that specifies the lowest or highest number in the range.
On the console, numeric ranges are inclusive. With the API, numeric ranges can be inclusive or exclusive, depending on the operator that you choose.

**Text (string)**  
Specifies a single text (string) value for a field. The string correlates to a predefined or existing value for a field—for example, *High* for the **Severity** field, the name of an S3 bucket for the **S3 bucket name** field, or the unique identifier for a sensitive data discovery job for the **Job ID** field.  
If you specify a single text string, note the following:  
+ Values are case sensitive.
+ You can’t use partial values or use wildcard characters in values. You have to specify a complete, valid value for the field. 
For example, to filter findings for an S3 bucket named *my-S3-bucket*, enter **my-S3-bucket** as the value for the **S3 bucket name** field. If you enter any other value, such as **my-s3-bucket** or **my-S3**, Macie won’t return findings for the bucket.  
For a list of valid values for each field, see [Fields for filtering Macie findings](findings-filter-fields.md).

## Specifying multiple values for a field
<a name="findings-filter-basics-multiple-values"></a>

With certain fields and operators, you can specify multiple values for a field. If you do this, Amazon Macie uses OR logic to join the values and evaluate the filter criteria. This means that a finding matches the criteria if it has *any* of the values for the field.

For example, if you add a condition to include findings where the value for the **Finding type** field equals *SensitiveData:S3Object/Financial, SensitiveData:S3Object/Personal*, Macie returns sensitive data findings for S3 objects that contain only financial information, and S3 objects that contain only personal information. In other words, Macie excludes all policy findings. Macie also excludes all sensitive data findings for objects that contain other types of sensitive data or multiple types of sensitive data. 

The exception is conditions that use the *eqExactMatch* operator. For this operator, Macie uses AND logic to join the values and evaluate the filter criteria. This means that a finding matches the criteria only if it has *all* the values for the field and *only* those values for the field. To learn more about this operator, see [Using operators in conditions](#findings-filter-basics-operators).

How you specify multiple values for a field depends on whether you use the Amazon Macie API or the Amazon Macie console. With the API, you use an array that lists the values.

On the console, you typically choose the values from a list. However, for some fields, you have to add a distinct condition for each value. For example, to include findings for data that Macie detected using certain custom data identifiers, do the following: 

1. Place your cursor in the **Filter criteria** box and then choose the **Custom data identifier name** field. Enter the name of a custom data identifier, and then choose **Apply**.

1. Repeat the preceding step for each additional custom data identifier that you want to specify for the filter.

For a list of fields that you need to do this for, see [Fields for filtering Macie findings](findings-filter-fields.md).

## Using operators in conditions
<a name="findings-filter-basics-operators"></a>

You can use the following types of operators in individual conditions.

**Equals (eq)**  
Matches (=) any value specified for the field. You can use the *equals* operator with the following types of values: array of text (strings), Boolean, date/time, number, and text (string).  
For many fields, you can use this operator and specify as many as 50 values for the field. If you do this, Amazon Macie uses OR logic to join the values. This means that a finding matches the criteria if it has *any* of the values specified for the field.  
For example:  
+ To include findings that report occurrences of financial information, personal information, or both financial and personal information, add a condition that uses the **Sensitive data category** field and this operator, and specify *Financial information* and *Personal information* as the values for the field.
+ To include findings that report occurrences of credit card numbers, mailing addresses, or both credit card numbers and mailing addresses, add a condition for the **Sensitive data detection type** field, use this operator, and specify *CREDIT\$1CARD\$1NUMBER* and *ADDRESS* as the values for the field.
If you use the Amazon Macie API to define a condition that uses this operator with a date/time value, specify the value as a Unix timestamp in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

**Equals exact match (eqExactMatch)**  
Exclusively matches all the values specified for the field. You can use the *equals exact match* operator with a select set of fields.   
If you use this operator and specify multiple values for a field, Macie uses AND logic to join the values. This means that a finding matches the criteria only if it has *all* the values specified for the field and *only* those values for the field. You can specify as many as 50 values for the field.  
For example:   
+ To include findings that report occurrences of credit card numbers and no other type of sensitive data, add a condition for the **Sensitive data detection type** field, use this operator, and specify *CREDIT\$1CARD\$1NUMBER* as the only value for the field.
+ To include findings that report occurrences of both credit card numbers and mailing addresses (and no other types of sensitive data), add a condition for the **Sensitive data detection type** field, use this operator, and specify *CREDIT\$1CARD\$1NUMBER* and *ADDRESS* as the values for the field.
Because Macie uses AND logic to join the values for a field, you can't use this operator in combination with any other operators for the same field. In other words, if you use the *equals exact match* operator with a field in one condition, you have to use it in all other conditions that use the same field.  
Like other operators, you can use the *equals exact match* operator in more than one condition in a filter. If you do this, Macie uses AND logic to join the conditions and evaluate the filter. This means that a finding matches the filter criteria only if it has *all* the values specified by *all* the conditions in the filter.  
For example, to include findings that were created after a certain time, report occurrences of credit card numbers, and don't report any other type of sensitive data, do the following:  

1. Add a condition that uses the **Created at** field, uses the *greater than* operator, and specifies the starting date and time for the filter.

1. Add another condition that uses the **Sensitive data detection type** field, uses the *equals exact match* operator, and specifies *CREDIT\$1CARD\$1NUMBER* as the only value for the field.
You can use the *equals exact match* operator with the following fields:  
+ Custom data identifier ID (`customDataIdentifiers.detections.arn`)
+ Custom data identifier name (`customDataIdentifiers.detections.name`)
+ S3 bucket tag key (`resourcesAffected.s3Bucket.tags.key`)
+ S3 bucket tag value (`resourcesAffected.s3Bucket.tags.value`)
+ S3 object tag key (`resourcesAffected.s3Object.tags.key`)
+ S3 object tag value (`resourcesAffected.s3Object.tags.value`)
+ Sensitive data detection type (`sensitiveData.detections.type`)
+ Sensitive data category (`sensitiveData.category`)
In the preceding list, the parenthetical name uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API.

**Greater than (gt)**  
Is greater than (>) the value specified for the field. You can use the *greater than* operator with number and date/time values.   
For example, to include only those findings that report more than 90 occurrences of sensitive data in an S3 object, add a condition that uses the **Sensitive data total count** field and this operator, and specify 90 as the value for the field. To do this on the Amazon Macie console, enter **91** in the **From** box, don't enter a value in the **To** box, and then choose **Apply**. Numeric and time-based comparisons are inclusive on the console.  
If you use the Amazon Macie API to define a time range that uses this operator, you have to specify the date/time values as Unix timestamps in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

**Greater than or equal to (gte)**  
Is greater than or equal to (>=) the value specified for the field. You can use the *greater than or equal to* operator with number and date/time values.  
For example, to include only those findings that report 90 or more occurrences of sensitive data in an S3 object, add a condition that uses the **Sensitive data total count** field and this operator, and specify 90 as the value for the field. To do this on the Amazon Macie console, enter **90** in the **From** box, don't enter a value in the **To** box, and then choose **Apply**.  
If you use the Amazon Macie API to define a time range that uses this operator, you have to specify the date/time values as Unix timestamps in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

**Less than (lt)**  
Is less than (<) the value specified for the field. You can use the *less than* operator with number and date/time values.  
For example, to include only those findings that report fewer than 90 occurrences of sensitive data in an S3 object, add a condition that uses the **Sensitive data total count** field and this operator, and specify 90 as the value for the field. To do this on the Amazon Macie console, enter **89** in the **To** box, don't enter a value in the **From** box, and then choose **Apply**. Numeric and time-based comparisons are inclusive on the console.  
If you use the Amazon Macie API to define a time range that uses this operator, you have to specify the date/time values as Unix timestamps in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

**Less than or equal to (lte)**  
Is less than or equal to (<=) the value specified for the field. You can use the *less than or equal to* operator with number and date/time values.  
For example, to include only those findings that report 90 or fewer occurrences of sensitive data in an S3 object, add a condition that uses the **Sensitive data total count** field and this operator, and specify 90 as the value for the field. To do this on the Amazon Macie console, enter **90** in the **To** box, don't enter a value in the **From** box, and then choose **Apply**.  
If you use the Amazon Macie API to define a time range that uses this operator, you have to specify the date/time values as Unix timestamps in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

**Not equals (neq)**  
Doesn't match (≠) any value specified for the field. You can use the *not equals* operator with the following types of values: array of text (strings), Boolean, date/time, number, and text (string).  
For many fields, you can use this operator and specify as many as 50 values for the field. If you do this, Macie uses OR logic to join the values. This means that a finding matches the criteria if it doesn't have *any* of the values specified for the field.  
For example:  
+ To exclude findings that report occurrences of financial information, personal information, or both financial and personal information, add a condition that uses the **Sensitive data category** field and this operator, and specify *Financial information* and *Personal information* as the values for the field.
+ To exclude findings that report occurrences of credit card numbers, add a condition for the **Sensitive data detection type** field, use this operator, and specify *CREDIT\$1CARD\$1NUMBER* as the value for the field.
+ To exclude findings that report occurrences of credit card numbers, mailing addresses, or both credit card numbers and mailing addresses, add a condition for the **Sensitive data detection type** field, use this operator, and specify *CREDIT\$1CARD\$1NUMBER* and *ADDRESS* as the values for the field.
If you use the Amazon Macie API to define a condition that uses this operator with a date/time value, specify the value as a Unix timestamp in milliseconds—for example, `1604616572653` for 22:49:32 UTC November 5, 2020.

# Fields for filtering Macie findings
<a name="findings-filter-fields"></a>

To help you analyze findings more efficiently, the Amazon Macie console and the Amazon Macie API provide access to several sets of fields for filtering findings:
+ **Common fields** – These fields store data that applies to any type of finding. They correlate to common attributes of findings, such as severity, finding type, and finding ID.
+ **Affected resource fields** – These fields store data about the resources that a finding applies to, such as the name, tags, and encryption settings for an affected S3 bucket or object.
+ **Fields for policy findings** – These fields store data that's specific to policy findings, such as the action that produced a finding, and the entity that performed the action.
+ **Fields for sensitive data findings** – These fields store data that's specific to sensitive data findings, such as the category and types of sensitive data that Macie found in an affected S3 object.

A filter can use a combination of fields from any of the preceding sets. The topics in this section list and describe individual fields in each set. For additional details about these fields, including any relationships between the fields, see [Findings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) in the *Amazon Macie API Reference*.

**Topics**
+ [Common fields](#findings-filter-fields-common)
+ [Affected resource fields](#findings-filter-fields-affected-resource)
+ [Fields for policy findings](#findings-filter-fields-policy)
+ [Fields for sensitive data findings](#findings-filter-fields-sd)

## Common fields
<a name="findings-filter-fields-common"></a>

The following table lists and describes fields that you can use to filter findings based on common finding attributes. These fields store data that applies to any type of finding.

In the table, the **Field** column indicates the name of the field on the Amazon Macie console. The **JSON field** column uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API. The **Description** column provides a brief description of the data that the field stores, and indicates any requirements for filter values. The table is sorted in ascending alphabetical order by field, and then by JSON field.


| Field | JSON field | Description | 
| --- | --- | --- | 
|  Account ID\$1  |  `accountId`  |  The unique identifier for the AWS account that the finding applies to. This is typically the account that owns the affected resource.  | 
| — |  `archived`  |  A Boolean value that specifies whether the finding was suppressed (automatically archived) by a suppression rule. To use this field in a filter on the console, choose an option on the **Finding status** menu: **Archived** (suppressed only), **Current** (unsuppressed only), or **All** (both suppressed and unsuppressed).  | 
|  Category  |  `category`  |  The category of the finding.  The console provides a list of values to choose from when you add this field to a filter. In the API, valid values are: `CLASSIFICATION`, for a sensitive data finding; and, `POLICY`, for a policy finding.  | 
| — |  `count`  |  The total number of occurrences of the finding. For sensitive data findings, this value is always `1`. All sensitive data findings are considered unique. This field isn't available as a filter option on the console. With the API, you can use this field to define a numeric range for a filter.  | 
|  Created at  |  `createdAt`  |  The date and time when Macie created the finding.You can use this field to define a time range for a filter.  | 
|  Finding ID\$1  |  `id`  |  The unique identifier for the finding. This is a random string that Macie generates and assigns to a finding when it creates the finding.  | 
|  Finding type\$1  |  `type`  |  The type of the finding—for example, `SensitiveData:S3Object/Personal` or `Policy:IAMUser/S3BucketPublic`.  The console provides a list of values to choose from when you add this field to a filter. For a list of valid values in the API, see [FindingType](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-findingtype) in the *Amazon Macie API Reference*.  | 
|  Region  |  `region`  |  The AWS Region that Macie created the finding in—for example, `us-east-1` or `ca-central-1`.  | 
|  Sample  |  `sample`  |  A Boolean value that specifies whether the finding is a sample finding. A *sample finding* is a finding that uses example data and placeholder values to demonstrate what a finding might contain. The console provides a list of values to choose from when you add this field to a filter.  | 
|  Severity  |  `severity.description`  |  The qualitative representation of the finding's severity.  The console provides a list of values to choose from when you add this field to a filter. In the API, valid values are: `Low`, `Medium`, and `High`.  | 
|  Updated at  |  `updatedAt`  |  The date and time when the finding was last updated. For sensitive data findings, this value is the same as the value for the **Created at** field. All sensitive data findings are considered new (unique). You can use this field to define a time range for a filter.  | 

\$1 To specify multiple values for this field on the console, add a condition that uses the field and specifies a distinct value for the filter, and then repeat that step for each additional value. To do this with the API, use an array that lists the values to use for the filter.

## Affected resource fields
<a name="findings-filter-fields-affected-resource"></a>

The following tables list and describe the fields that you can use to filter findings based on the type of resource that a finding applies to: an [S3 bucket](#findings-filter-fields-affected-resource-S3bucket) or an [S3 object](#findings-filter-fields-affected-resource-S3object).

### S3 bucket
<a name="findings-filter-fields-affected-resource-S3bucket"></a>

This table lists and describes fields that you can use to filter findings based on characteristics of the S3 bucket that a finding applies to.

In the table, the **Field** column indicates the name of the field on the Amazon Macie console. The **JSON field** column uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API. (Longer JSON field names use the newline character sequence (`\n`) to improve readability.) The **Description** column provides a brief description of the data that the field stores, and indicates any requirements for filter values. The table is sorted in ascending alphabetical order by field, and then by JSON field.


| Field | JSON field | Description | 
| --- | --- | --- | 
|  —  |  `resourcesAffected.s3Bucket.createdAt`  |  The date and time when the affected bucket was created, or changes such as edits to the bucket's policy were most recently made to the affected bucket. This field isn't available as a filter option on the console. With the API, you can use this field to define a time range for a filter.  | 
|  S3 bucket default encryption  |  `resourcesAffected.s3Bucket.\n` `defaultServerSideEncryption.encryptionType`  |  The server-side encryption algorithm that's used by default to encrypt objects that are added to the affected bucket. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for the API, see [EncryptionType](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-encryptiontype) in the *Amazon Macie API Reference*.  | 
|  S3 bucket encryption KMS key id\$1  |  `resourcesAffected.s3Bucket.\n` `defaultServerSideEncryption.kmsMasterKeyId`  |  The Amazon Resource Name (ARN) or unique identifier (key ID) for the AWS KMS key that's used by default to encrypt objects that are added to the affected bucket.  | 
|  S3 bucket encryption required by bucket policy  |  `resourcesAffected.s3Bucket.allowsUnencryptedObjectUploads`  |  Specifies whether the bucket policy for the affected bucket requires server-side encryption of objects when objects are added to the bucket. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for the API, see [S3Bucket](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-s3bucket) in the *Amazon Macie API Reference*.  | 
|  S3 bucket name\$1  |  `resourcesAffected.s3Bucket.name`  |  The full name of the affected bucket.  | 
|  S3 bucket owner display name\$1  |  `resourcesAffected.s3Bucket.owner.displayName`  |  The display name of the AWS user who owns the affected bucket.  | 
|  S3 bucket public access permission  |  `resourcesAffected.s3Bucket.publicAccess.effectivePermission`  |  Specifies whether the affected bucket is publicly accessible based on a combination of permissions settings that apply to the bucket. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for the API, see [BucketPublicAccess](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-bucketpublicaccess) in the *Amazon Macie API Reference*.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.accountLevelPermissions.\n` `blockPublicAccess.blockPublicAcls`  |  A Boolean value that specifies whether Amazon S3 blocks public access control lists (ACLs) for the affected bucket and objects in the bucket. This is an account-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.accountLevelPermissions.\n` `blockPublicAccess.blockPublicPolicy`  |  A Boolean value that specifies whether Amazon S3 blocks public bucket policies for the affected bucket. This is an account-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.accountLevelPermissions.\n` `blockPublicAccess.ignorePublicAcls`  |  A Boolean value that specifies whether Amazon S3 ignores public ACLs for the affected bucket and objects in the bucket. This is an account-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.accountLevelPermissions.\n` `blockPublicAccess.restrictPublicBuckets`  |  A Boolean value that specifies whether Amazon S3 restricts public bucket policies for the affected bucket. This is an account-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `accessControlList.allowsPublicReadAccess`  |  A Boolean value that specifies whether the bucket-level ACL for the affected bucket grants the general public with read access permissions for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `accessControlList.allowsPublicWriteAccess`  |  A Boolean value that specifies whether the bucket-level ACL for the affected bucket grants the general public with write access permissions for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `blockPublicAccess.blockPublicAcls`  |  A Boolean value that specifies whether Amazon S3 blocks public ACLs for the affected bucket and objects in the bucket. This is a bucket-level, block public access setting for a bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `blockPublicAccess.blockPublicPolicy`  |  A Boolean value that specifies whether Amazon S3 blocks public bucket policies for the affected bucket. This is a bucket-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `blockPublicAccess.ignorePublicAcls`  |  A Boolean value that specifies whether Amazon S3 ignores public ACLs for the affected bucket and objects in the bucket. This is a bucket-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `blockPublicAccess.restrictPublicBuckets`  |  A Boolean value that specifies whether Amazon S3 restricts public bucket policies for the affected bucket. This is a bucket-level, block public access setting for the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `bucketPolicy.allowsPublicReadAccess`  |  A Boolean value that specifies whether the affected bucket's policy allows the general public to have read access to the bucket. This field isn't available as a filter option on the console.  | 
|  —  |  `resourcesAffected.s3Bucket.publicAccess.\n` `permissionConfiguration.bucketLevelPermissions.\n` `bucketPolicy.allowsPublicWriteAccess`  |  A Boolean value that specifies whether the affected bucket's policy allows the general public to have write access to the bucket. This field isn't available as a filter option on the console.  | 
|  S3 bucket tag key\$1  |  `resourcesAffected.s3Bucket.tags.key`  |  A tag key that's associated with the affected bucket.  | 
|  S3 bucket tag value\$1  |  `resourcesAffected.s3Bucket.tags.value`  |  A tag value that's associated with the affected bucket.  | 

\$1 To specify multiple values for this field on the console, add a condition that uses the field and specifies a distinct value for the filter, and then repeat that step for each additional value. To do this with the API, use an array that lists the values to use for the filter.

### S3 object
<a name="findings-filter-fields-affected-resource-S3object"></a>

This table lists and describes fields that you can use to filter findings based on characteristics of the S3 object that a finding applies to.

In the table, the **Field** column indicates the name of the field on the Amazon Macie console. The **JSON field** column uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API. (Longer JSON field names use the newline character sequence (`\n`) to improve readability.) The **Description** column provides a brief description of the data that the field stores, and indicates any requirements for filter values. The table is sorted in ascending alphabetical order by field, and then by JSON field.


| Field | JSON field | Description | 
| --- | --- | --- | 
|  S3 object encryption KMS key id\$1  |  `resourcesAffected.s3Object.\n` `serverSideEncryption.kmsMasterKeyId`  |  The Amazon Resource Name (ARN) or unique identifier (key ID) for the AWS KMS key that was used to encrypt the affected object.  | 
|  S3 object encryption type  |  `resourcesAffected.s3Object.\n` `serverSideEncryption.encryptionType`  |  The server-side encryption algorithm that was used to encrypt the affected object. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for the API, see [EncryptionType](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-encryptiontype) in the *Amazon Macie API Reference*.  | 
| — |  `resourcesAffected.s3Object.extension`  |  The file name extension of the affected object. For objects that don't have a file name extension, specify `""` as the value for the filter. This field isn't available as a filter option on the console.  | 
| — |  `resourcesAffected.s3Object.lastModified`  |  The date and time when the affected object was created or last changed, whichever is latest. This field isn't available as a filter option on the console. With the API, you can use this field to define a time range for a filter.  | 
| S3 object key\$1 |  `resourcesAffected.s3Object.key`  |  The full name (*key*) of the affected object, including the object's prefix if applicable.  | 
| — |  `resourcesAffected.s3Object.path`  |  The full path to the affected object, including the name of the affected bucket and the object's name (*key*). This field isn't available as a filter option on the console.  | 
| S3 object public access |  `resourcesAffected.s3Object.publicAccess`  |  A Boolean value that specifies whether the affected object is publicly accessible based on a combination of permission settings that apply to the object. The console provides a list of values to choose from when you add this field to a filter.  | 
| S3 object tag key\$1 |  `resourcesAffected.s3Object.tags.key`  |  A tag key that's associated with the affected object.  | 
| S3 object tag value\$1 |  `resourcesAffected.s3Object.tags.value`  |  A tag value that's associated with the affected object.  | 

\$1 To specify multiple values for this field on the console, add a condition that uses the field and specifies a distinct value for the filter, and then repeat that step for each additional value. To do this with the API, use an array that lists the values to use for the filter.

## Fields for policy findings
<a name="findings-filter-fields-policy"></a>

The following table lists and describes fields that you can use to filter policy findings. These fields store data that's specific to policy findings.

In the table, the **Field** column indicates the name of the field on the Amazon Macie console. The **JSON field** column uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API. (Longer JSON field names use the newline character sequence (`\n`) to improve readability.) The **Description** column provides a brief description of the data that the field stores, and indicates any requirements for filter values. The table is sorted in ascending alphabetical order by field, and then by JSON field.


| Field | JSON field | Description | 
| --- | --- | --- | 
|  Action type  |  `policyDetails.action.actionType`  |  The type of action that produced the finding. The only valid value for this field is `AWS_API_CALL`.  | 
|  API call name\$1  |  `policyDetails.action.apiCallDetails.api`  |  The name of the operation that was invoked most recently and produced the finding.  | 
|  API service name\$1  |  `policyDetails.action.apiCallDetails.apiServiceName`  |  The URL of the AWS service that provides the operation that was invoked and produced the finding—for example, `s3.amazonaws.com`.  | 
|  —  | `policyDetails.action.apiCallDetails.firstSeen` | The first date and time when any operation was invoked and produced the finding.This field isn't available as a filter option on the console. With the API, you can use this field to define a time range for a filter. | 
|  —  | `policyDetails.action.apiCallDetails.lastSeen` | The most recent date and time when the specified operation (**API call name** or `api`) was invoked and produced the finding.This field isn't available as a filter option on the console. With the API, you can use this field to define a time range for a filter. | 
|  —  | `policyDetails.actor.domainDetails.domainName` | The domain name of the device that was used to perform the action.This field isn't available as a filter option on the console. | 
|  IP city\$1  |  `policyDetails.actor.ipAddressDetails.ipCity.name`  |  The name of the originating city for the IP address of the device that was used to perform the action.  | 
|  IP country\$1  |  `policyDetails.actor.ipAddressDetails.ipCountry.name`  |  The name of the originating country for the IP address of the device that was used to perform the action—for example, `United States`.  | 
|  —  | `policyDetails.actor.ipAddressDetails.ipOwner.asn` | The Autonomous System Number (ASN) for the autonomous system that included the IP address of the device that was used to perform the action.This field isn't available as a filter option on the console. | 
|  IP owner ASN org\$1  |  `policyDetails.actor.ipAddressDetails.ipOwner.asnOrg`  |  The organization identifier that's associated with the ASN for the autonomous system that included the IP address of the device that was used to perform the action.  | 
|  IP owner ISP\$1  |  `policyDetails.actor.ipAddressDetails.ipOwner.isp`  |  The name of the internet service provider (ISP) that owned the IP address of the device that was used to perform the action.  | 
|  IP V4 address\$1  |  `policyDetails.actor.ipAddressDetails.ipAddressV4`  |  The Internet Protocol version 4 (IPv4) address of the device that was used to perform the action.  | 
|  —  | `policyDetails.actor.userIdentity.\n` `assumedRole.accessKeyId` | For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the AWS access key ID that identifies the credentials.This field isn't available as a filter option on the console. | 
|  User identity assumed role account id\$1  |  `policyDetails.actor.userIdentity.\n` `assumedRole.accountId`  |  For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the unique identifier for the AWS account that owns the entity that was used to get the credentials.  | 
| User identity assumed role principal id\$1 |  `policyDetails.actor.userIdentity.\n` `assumedRole.principalId`  |  For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the unique identifier for the entity that was used to get the credentials.  | 
| User identity assumed role session ARN\$1 |  `policyDetails.actor.userIdentity.\n` `assumedRole.arn`  |  For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the Amazon Resource Name (ARN) of the source account, IAM user, or role that was used to get the credentials.  | 
|  —  | `policyDetails.actor.userIdentity.\n` `assumedRole.sessionContext.sessionIssuer.type` | For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the source of the temporary security credentials— for example, `Root`, `IAMUser`, or `Role`.This field isn't available as a filter option on the console. | 
|  —  | `policyDetails.actor.userIdentity.\n` `assumedRole.sessionContext.sessionIssuer.userName` | For an action performed with temporary security credentials that were obtained using the `AssumeRole` operation of the AWS STS API, the name or alias of the user or role that issued the session. Note that this value is null if the credentials were obtained from a root account that doesn't have an alias.This field isn't available as a filter option on the console. | 
| User identity AWS account account id\$1 |  `policyDetails.actor.userIdentity.\n` `awsAccount.accountId`  | For an action performed using the credentials for another AWS account, the unique identifier for the account. | 
| User identity AWS account principal id\$1 |  `policyDetails.actor.userIdentity.\n` `awsAccount.principalId`  |  For an action performed using the credentials for another AWS account, the unique identifier for the entity that performed the action.  | 
| User identity AWS service invoked by |  `policyDetails.actor.userIdentity.\n` `awsService.invokedBy`  |  For an action performed by an account that belongs to an AWS service, the name of the service.  | 
|  —  | `policyDetails.actor.userIdentity.\n` `federatedUser.accessKeyId` | For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the AWS access key ID that identifies the credentials.This field isn't available as a filter option on the console. | 
| User identity federated session ARN\$1 |  `policyDetails.actor.userIdentity.\n` `federatedUser.arn`  |  For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the ARN of the entity that was used to get the credentials.  | 
| User identity federated user account id\$1 |  `policyDetails.actor.userIdentity.\n` `federatedUser.accountId`  |  For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the unique identifier for the AWS account that owns the entity that was used to get the credentials.  | 
| User identity federated user principal id\$1 |  `policyDetails.actor.userIdentity.\n` `federatedUser.principalId`  |  For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the unique identifier for the entity that was used to get the credentials.  | 
|  —  | `policyDetails.actor.userIdentity.\n` `federatedUser.sessionContext.sessionIssuer.type` | For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the source of the temporary security credentials—for example, `Root`, `IAMUser`, or `Role`.This field isn't available as a filter option on the console. | 
|  —  | `policyDetails.actor.userIdentity.\n` `federatedUser.sessionContext.sessionIssuer.userName` | For an action performed with temporary security credentials that were obtained using the `GetFederationToken` operation of the AWS STS API, the name or alias of the user or role that issued the session. Note that this value is null if the credentials were obtained from a root account that doesn't have an alias.This field isn't available as a filter option on the console. | 
| User identity IAM account id\$1 |  `policyDetails.actor.userIdentity.\n` `iamUser.accountId`  |  For an action performed using an IAM user's credentials, the unique identifier for the AWS account that's associated with the IAM user who performed the action.  | 
| User identity IAM principal id\$1 |  `policyDetails.actor.userIdentity.\n` `iamUser.principalId`  |  For an action performed using an IAM user's credentials, the unique identifier for the IAM user who performed the action.  | 
| User identity IAM user name\$1 |  `policyDetails.actor.userIdentity.\n` `iamUser.userName`  |  For an action performed using an IAM user's credentials, the username of the IAM user who performed the action.  | 
| User identity root account id\$1 |  `policyDetails.actor.userIdentity.\n` `root.accountId`  |  For an action performed using the credentials for your AWS account, the unique identifier for the account.  | 
| User identity root principal id\$1 |  `policyDetails.actor.userIdentity.\n` `root.principalId`  |  For an action performed using the credentials for your AWS account, the unique identifier for the entity that performed the action.  | 
| User identity type |  `policyDetails.actor.userIdentity.type`  |  The type of entity that performed the action that produced the finding. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for the API, see [UserIdentityType](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html#findings-describe-model-useridentitytype) in the *Amazon Macie API Reference*.  | 

\$1 To specify multiple values for this field on the console, add a condition that uses the field and specifies a distinct value for the filter, and then repeat that step for each additional value. To do this with the API, use an array that lists the values to use for the filter.

## Fields for sensitive data findings
<a name="findings-filter-fields-sd"></a>

The following table lists and describes fields that you can use to filter sensitive data findings. These fields store data that's specific to sensitive data findings.

In the table, the **Field** column indicates the name of the field on the Amazon Macie console. The **JSON field** column uses dot notation to indicate the name of the field in JSON representations of findings and the Amazon Macie API. (Longer JSON field names use the newline character sequence (`\n`) to improve readability.) The **Description** column provides a brief description of the data that the field stores, and indicates any requirements for filter values. The table is sorted in ascending alphabetical order by field, and then by JSON field.


| Field | JSON field | Description | 
| --- | --- | --- | 
|  Custom data identifier ID\$1  |  `classificationDetails.result.\n` `customDataIdentifiers.detections.arn`  |  The unique identifier for the custom data identifier that detected the data and produced the finding.   | 
|  Custom data identifier name\$1  |  `classificationDetails.result.\n` `customDataIdentifiers.detections.name`  |  The name of the custom data identifier that detected the data and produced the finding.  | 
|  Custom data identifier total count  |  `classificationDetails.result.\n` `customDataIdentifiers.detections.count`  |  The total number of occurrences of data that was detected by custom data identifiers and produced the finding. You can use this field to define a numeric range for a filter.  | 
|  Job ID\$1  |  `classificationDetails.jobId`  |  The unique identifier for the sensitive data discovery job that produced the finding.  | 
|  Origin type  | `classificationDetails.originType` | How Macie found the sensitive data that produced the finding: `AUTOMATED_SENSITIVE_DATA_DISCOVERY` or `SENSITIVE_DATA_DISCOVERY_JOB`.   | 
|  —  | `classificationDetails.result.mimeType` | The type of content, as a MIME type, that the finding applies to—for example, `text/csv` for a CSV file or `application/pdf` for an Adobe Portable Document Format file.This field isn't available as a filter option on the console. | 
|  —  | `classificationDetails.result.sizeClassified` | The total storage size, in bytes, of the S3 object that the finding applies to.This field isn't available as a filter option on the console. With the API, you can use this field to define a numeric range for a filter. | 
|  Result status code\$1  |  `classificationDetails.result.status.code`  |  The status of the finding. Valid values are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/macie/latest/user/findings-filter-fields.html)  | 
|  Sensitive data category  |  `classificationDetails.result.\n` `sensitiveData.category`  |  The category of sensitive data that was detected and produced the finding. The console provides a list of values to choose from when you add this field to a filter. In the API, valid values are: `CREDENTIALS`, `FINANCIAL_INFORMATION`, and `PERSONAL_INFORMATION`.  | 
|  Sensitive data detection type  |  `classificationDetails.result.\n` `sensitiveData.detections.type`  |  The type of sensitive data that was detected and produced the finding. This is the unique identifier for the managed data identifier that detected the data. The console provides a list of values to choose from when you add this field to a filter. For a list of valid values for both the console and the API, see [Quick reference: Managed data identifiers by type](mdis-reference-quick.md).  | 
|  Sensitive data total count  |  `classificationDetails.result.\n` `sensitiveData.detections.count`  |  The total number of occurrences of the type of sensitive data that was detected and produced the finding. You can use this field to define a numeric range for a filter.  | 

\$1 To specify multiple values for this field on the console, add a condition that uses the field and specifies a distinct value for the filter, and then repeat that step for each additional value. To do this with the API, use an array that lists the values to use for the filter.

# Creating and applying filters to Macie findings
<a name="findings-filter-procedure"></a>

To identify and focus on findings that have specific characteristics, you can filter findings on the Amazon Macie console and in queries that you submit programmatically using the Amazon Macie API. When you create a filter, you use specific attributes of findings to define criteria for including or excluding findings from a view or from query results. A *finding attribute* is a field that stores specific data for a finding, such as severity, type, or the name of the resource that a finding applies to.

In Macie, a filter consists of one or more conditions. Each condition, also referred to as a *criterion*, consists of three parts: 
+ An attribute-based field, such as **Severity** or **Finding type**.
+ An operator, such as *equals* or *not equals*.
+ One or more values. The type and number of values depends on the field and operator that you choose.

How you define and apply filter conditions depends on whether you use the Amazon Macie console or the Amazon Macie API.

**Topics**
+ [Filtering findings by using the console](#findings-filter-procedure-console)
+ [Filtering findings programmatically](#findings-filter-procedure-api)

## Filtering findings by using the Amazon Macie console
<a name="findings-filter-procedure-console"></a>

If you use the Amazon Macie console to filter findings, Macie provides options to help you choose fields, operators, and values for individual conditions. You access these options by using filter settings on **Findings** pages, as shown in the following image.

![\[The filter settings on a Findings page, the Finding status menu and the Filter criteria box.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-empty.png)


By using the **Finding status** menu, you can specify whether to include findings that were suppressed (automatically archived) by a [suppression rule](findings-suppression.md). By using the **Filter criteria** box, you can enter filter conditions.

When you place your cursor in the **Filter criteria** box, Macie displays a list of fields that you can use in filter conditions. The fields are organized by logical category. For example, the **Common fields** category includes fields that apply to any type of finding, and the **Classification fields** category includes fields that apply only to sensitive data findings. The fields are sorted alphabetically within each category.

To add a condition, start by choosing a field from the list. To find a field, browse the complete list, or enter part of the field's name to narrow the list of fields.

Depending on the field that you choose, Macie displays different options. The options reflect the type and nature of the field that you choose. For example, if you choose the **Severity** field, Macie displays a list of values to choose from—**Low**, **Medium**, and **High**. If you choose the **S3 bucket name** field, Macie displays a text box in which you can enter a bucket name. Whichever field you choose, Macie guides you through the steps to add a condition that includes the required settings for the field.

After you add a condition, Macie applies the criteria for the condition and adds the condition to a filter token in the **Filter criteria** box, as shown in the following image. 

![\[The Filter criteria box with a token for a condition that specifies values for the Severity field.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-severity.png)


In this example, the condition is configured to include all medium-severity and high-severity findings, and to exclude all low-severity findings. It returns findings where the value for the **Severity** field *equals* **Medium** or **High**.

**Tip**  
For many fields, you can change a condition's operator from *equals* to *not equals* by choosing the equals icon (![\[The equals icon, which is a solid gray circle.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-operator-equals.png)) in the filter token for the condition. If you do this, Macie changes the operator to *not equals* and displays the not equals icon (![\[The not equals icon, which is an empty gray circle that has a backslash in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-operator-not-equals.png)) in the token. To switch to the *equals* operator again, choose the not equals icon. 

As you add more conditions, Macie applies their criteria and adds them to tokens in the **Filter criteria** box. You can refer to the box at any time to determine which criteria you've applied. To remove a condition, choose the remove condition icon (![\[The remove filter condition icon, which is a circle that has an X in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-filter-remove.png)) in the token for the condition.

**To filter findings by using the console**

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. (Optional) To first pivot on and review findings by a predefined logical group, choose **By bucket**, **By type**, or **By job** in the navigation pane (under **Findings**). Then choose an item in the table. In the details panel, choose the link for the field to pivot on.

1. (Optional) To display findings that were suppressed by a [suppression rule](findings-suppression.md), change the **Filter status** setting. Choose **Archived** to display only suppressed findings, or choose **All** to display both suppressed and unsuppressed findings. To hide suppressed findings, choose **Current**.

1. To add a filter condition:

   1. Place your cursor in the **Filter criteria** box, and then choose the field to use for the condition. For information about the fields that you can use, see [Fields for filtering Macie findings](findings-filter-fields.md).

   1. Enter the appropriate type of value for the field. For detailed information about the different types of values, see [Specifying values for fields](findings-filter-basics.md#findings-filter-basics-value-types).

        
**Array of text (strings)**  
For this type of value, Macie often provides a list of values to choose from. If this is the case, select each value that you want to use in the condition.  
If Macie doesn't provide a list of values, enter a complete, valid value for the field. To specify additional values for the field, choose **Apply**, and then add another condition for each additional value.  
Note that values are case sensitive. In addition, you can’t use partial values or wildcard characters in values. For example, to filter findings for an S3 bucket named *my-S3-bucket*, enter **my-S3-bucket** as the value for the **S3 bucket name** field. If you enter any other value, such as **my-s3-bucket** or **my-S3**, Macie won’t return findings for the bucket.  
**Boolean**  
For this type of value, Macie provides a list of values to choose from. Select the value that you want to use in the condition.  
**Date/Time (time ranges)**  
For this type of value, use the **From** and **To** boxes to define an inclusive time range:  
      + To define a fixed time range, use the **From** and **To** boxes to specify the first date and time and the last date and time in the range, respectively.
      + To define a relative time range that starts at a certain date and time and ends at the current time, enter the start date and time in the **From** boxes, and delete any text in **To** boxes.
      + To define a relative time range that ends at a certain date and time, enter the end date and time in the **To** boxes, and delete any text in the **From** boxes.
Note that time values use 24-hour notation. If you use the date picker to choose dates, you can refine the values by entering text directly in the **From** and **To** boxes.  
**Number (numeric ranges)**  
For this type of value, use the **From** and **To** boxes to enter one or more integers that define an inclusive, fixed or relative numeric range.  
**Text (string) values**  
For this type of value, enter a complete, valid value for the field.  
Note that values are case sensitive. In addition, you can’t use partial values or wildcard characters in values. For example, to filter findings for an S3 bucket named *my-S3-bucket*, enter **my-S3-bucket** as the value for the **S3 bucket name** field. If you enter any other value, such as **my-s3-bucket** or **my-S3**, Macie won’t return findings for the bucket.

   1. When you finish adding values for the field, choose **Apply**. Macie applies the filter criteria and adds the condition to a filter token in the **Filter criteria** box.

1. Repeat step 5 for each additional condition that you want to add.

1. To remove a condition, choose the remove condition icon (![\[The remove filter condition icon, which is a circle that has an X in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-filter-remove.png)) in the filter token for the condition.

1. To change a condition, remove the condition by choosing the remove condition icon (![\[The remove filter condition icon, which is a circle that has an X in it.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-filter-remove.png)) in the filter token for the condition. Then repeat step 5 to add a condition with the correct settings.

**Tip**  
If you want to subsequently use this set of conditions again, you can save the set as a filter rule. To do this, choose **Save rule** in the **Filter criteria** box. Then enter a name and, optionally, a description for the rule. When you finish, choose **Save**.

## Filtering findings programmatically with the Amazon Macie API
<a name="findings-filter-procedure-api"></a>

To filter findings programmatically, specify filter criteria in queries that you submit using the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) or [GetFindingStatistics](https://docs.aws.amazon.com/macie/latest/APIReference/findings-statistics.html) operation of the Amazon Macie API. The **ListFindings** operation returns an array of finding IDs, one ID for each finding that matches the filter criteria. The **GetFindingStatistics** operation returns aggregated statistical data about all the findings that match the filter criteria, grouped by a field that you specify in your request.

Note that the **ListFindings** and **GetFindingStatistics** operations are different from operations that you use to [suppress findings](findings-suppression.md). Unlike suppression operations, which also specify filter criteria, the **ListFindings** and **GetFindingStatistics** operations only query findings data. They don't perform any action on findings that match filter criteria. To suppress findings, use the [CreateFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation of the Amazon Macie API.

To specify filter criteria in a query, include a map of filter conditions in your request. For each condition, specify a field, an operator, and one or more values for the field. The type and number of values depends on the field and operator that you choose. For information about the fields, operators, and types of values that you can use in a condition, see [Fields for filtering Macie findings](findings-filter-fields.md), [Using operators in conditions](findings-filter-basics.md#findings-filter-basics-operators), and [Specifying values for fields](findings-filter-basics.md#findings-filter-basics-value-types).

The following examples show you how to specify filter criteria in queries that you submit using the [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). You can also do this by using a current version of another AWS command line tool or an AWS SDK, or by sending HTTPS requests directly to Macie. For information about AWS tools and SDKs, see [Tools to Build on AWS](https://aws.amazon.com/developer/tools/).

**Topics**
+ [Filter findings based on severity](#findings-filter-procedure-api-ex1)
+ [Filter findings based on sensitive data category](#findings-filter-procedure-api-ex2)
+ [Filter findings based on a fixed time range](#findings-filter-procedure-api-ex3)
+ [Filter findings based on suppression status](#findings-filter-procedure-api-ex4)
+ [Filter findings based on multiple fields and types of values](#findings-filter-procedure-api-ex5)

The examples use the [list-findings](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings.html) command. If an example runs successfully, Macie returns a `findingIds` array. The array lists the unique identifier for each finding that matches the filter criteria, as shown in the following example.

```
{
    "findingIds": [
        "1f1c2d74db5d8caa76859ec52example",
        "6cfa9ac820dd6d55cad30d851example",
        "702a6fd8750e567d1a3a63138example",
        "826e94e2a820312f9f964cf60example",
        "274511c3fdcd87010a19a3a42example"
    ]
}
```

If no findings match the filter criteria, Macie returns an empty `findingIds` array.

```
{
    "findingIds": []
}
```

### Example 1: Filter findings based on severity
<a name="findings-filter-procedure-api-ex1"></a>

This example retrieves finding IDs for all high-severity and medium-severity findings in the current AWS Region.

For Linux, macOS, or Unix:

```
$ aws macie2 list-findings --finding-criteria '{"criterion":{"severity.description":{"eq":["High","Medium"]}}}'
```

For Microsoft Windows:

```
C:\> aws macie2 list-findings --finding-criteria={\"criterion\":{\"severity.description\":{\"eq\":[\"High\",\"Medium\"]}}}
```

Where:
+ *severity.description* specifies the JSON name of the **Severity** field.
+ *eq* specifies the *equals* operator.
+ *High* and *Medium* are an array of enumerated values for the **Severity** field.

### Example 2: Filter findings based on sensitive data category
<a name="findings-filter-procedure-api-ex2"></a>

This example retrieves finding IDs for all sensitive data findings that are in the current Region and report occurrences of financial information (and no other categories of sensitive data) in S3 objects.

For Linux, macOS, or Unix, using the backslash (\$1) line-continuation character to improve readability:

```
$ aws macie2 list-findings \
--finding-criteria '{"criterion":{"classificationDetails.result.sensitiveData.category":{"eqExactMatch":["FINANCIAL_INFORMATION"]}}}'
```

For Microsoft Windows, using the caret (^) line-continuation character to improve readability:

```
C:\> aws macie2 list-findings ^
--finding-criteria={\"criterion\":{\"classificationDetails.result.sensitiveData.category\":{\"eqExactMatch\":[\"FINANCIAL_INFORMATION\"]}}}
```

Where:
+ *classificationDetails.result.sensitiveData.category* specifies the JSON name of the **Sensitive data category** field.
+ *eqExactMatch* specifies the *equals exact match* operator.
+ *FINANCIAL\$1INFORMATION* is an enumerated value for the **Sensitive data category** field.

### Example 3: Filter findings based on a fixed time range
<a name="findings-filter-procedure-api-ex3"></a>

This example retrieves finding IDs for all findings that are in the current Region and were created between 07:00 UTC October 5, 2020, and 07:00 UTC November 5, 2020 (inclusively).

For Linux, macOS, or Unix:

```
$ aws macie2 list-findings --finding-criteria '{"criterion":{"createdAt":{"gte":1601881200000,"lte":1604559600000}}}'
```

For Microsoft Windows:

```
C:\> aws macie2 list-findings --finding-criteria={\"criterion\":{\"createdAt\":{\"gte\":1601881200000,\"lte\":1604559600000}}}
```

Where:
+ *createdAt* specifies the JSON name of the **Created at** field.
+ *gte* specifies the *greater than or equal to* operator.
+ *1601881200000* is the first date and time (as a Unix timestamp in milliseconds) in the time range.
+ *lte* specifies the *less than or equal to* operator.
+ *1604559600000* is the last date and time (as a Unix timestamp in milliseconds) in the time range.

### Example 4: Filter findings based on suppression status
<a name="findings-filter-procedure-api-ex4"></a>

This example retrieves finding IDs for all findings that are in the current Region and were suppressed (automatically archived) by a suppression rule.

For Linux, macOS, or Unix:

```
$ aws macie2 list-findings --finding-criteria '{"criterion":{"archived":{"eq":["true"]}}}'
```

For Microsoft Windows:

```
C:\> aws macie2 list-findings --finding-criteria={\"criterion\":{\"archived\":{\"eq\":[\"true\"]}}}
```

Where:
+ *archived* specifies the JSON name of the **Archived** field.
+ *eq* specifies the *equals* operator.
+ *true* is a Boolean value for the **Archived** field.

### Example 5: Filter findings based on multiple fields and types of values
<a name="findings-filter-procedure-api-ex5"></a>

This example retrieves finding IDs for all sensitive data findings that are in the current Region and match the following criteria: were created between 07:00 UTC October 5, 2020, and 07:00 UTC November 5, 2020 (exclusively); report occurrences of financial data and no other categories of sensitive data in S3 objects; and weren't suppressed (automatically archived) by a suppression rule.

For Linux, macOS, or Unix, using the backslash (\$1) line-continuation character to improve readability:

```
$ aws macie2 list-findings \
--finding-criteria '{"criterion":{"createdAt":{"gt":1601881200000,"lt":1604559600000},"classificationDetails.result.sensitiveData.category":{"eqExactMatch":["FINANCIAL_INFORMATION"]},"archived":{"eq":["false"]}}}'
```

For Microsoft Windows, using the caret (^) line-continuation character to improve readability:

```
C:\> aws macie2 list-findings ^
--finding-criteria={\"criterion\":{\"createdAt\":{\"gt\":1601881200000,\"lt\":1604559600000},\"classificationDetails.result.sensitiveData.category\":{\"eqExactMatch\":[\"FINANCIAL_INFORMATION\"]},\"archived\":{\"eq\":[\"false\"]}}}
```

Where:
+ *createdAt* specifies the JSON name of the **Created at** field, and:
  + *gt* specifies the *greater than or equal to* operator.
  + *1601881200000* is the first date and time (as a Unix timestamp in milliseconds) in the time range.
  + *lt* specifies the *less than or equal to* operator.
  + *1604559600000* is the last date and time (as a Unix timestamp in milliseconds) in the time range.
+ *classificationDetails.result.sensitiveData.category* specifies the JSON name of the **Sensitive data category** field, and:
  + *eqExactMatch* specifies the *equals exact match* operator.
  + *FINANCIAL\$1INFORMATION* is an enumerated value for the field.
+ *archived* specifies the JSON name of the **Archived** field, and:
  + *eq* specifies the *equals* operator.
  + *false* is a Boolean value for the field.

# Defining filter rules for Macie findings
<a name="findings-filter-rule-procedures"></a>

To perform consistent analysis of findings, you can create and apply filter rules. A *filter rule* is a set of filter criteria that you create and save to use again when you review findings on the Amazon Macie console. Filter rules can help you perform repeated, consistent analysis of findings that have specific characteristics. For example, you might create one filter rule for analyzing all high-severity sensitive data findings that report specific types of sensitive data. You might create another filter rule for analyzing all high-severity policy findings for Amazon Simple Storage Service (Amazon S3) buckets that store unencrypted objects.

When you create a filter rule, you use specific attributes of findings to define criteria for including or excluding findings from a view. A *finding attribute* is a field that stores specific data for a finding, such as severity, type, or the name of the S3 bucket that a finding applies to. You also specify a name, and, optionally, a description of the rule. To then analyze findings that match the criteria of the rule, choose the rule. Macie applies the rule's criteria and displays only those findings that match the criteria. Macie also displays the criteria to help you determine which criteria it applied.

Note that filter rules are different from suppression rules. A *suppression rule* is a set of filter criteria that you create and save to automatically archive findings that match the criteria of the rule. Although both types of rules store and apply filter criteria, a filter rule doesn't perform any action on findings that match the rule's criteria. Instead, a filter rule only determines which findings appear on the console after you apply the rule. For information about suppression rules, see [Suppressing findings](findings-suppression.md).

**Topics**
+ [Creating a filter rule](findings-filter-rule-create.md)
+ [Applying a filter rule](findings-filter-rule-apply.md)
+ [Changing a filter rule](findings-filter-rule-change.md)
+ [Deleting a filter rule](findings-filter-rule-delete.md)

# Creating a filter rule for Macie findings
<a name="findings-filter-rule-create"></a>

A *filter rule* is a set of filter criteria that you create and save to use again when you review findings on the Amazon Macie console. Filter rules can help you perform repeated, consistent analysis of findings that have specific characteristics. For example, you might create a filter rule for analyzing all high-severity sensitive data findings that report occurrences of sensitive data in particular Amazon Simple Storage Service (Amazon S3) buckets. You can then apply that filter rule each time you want to identify and analyze findings that have the specified characteristics.

When you create a filter rule, you specify filter criteria, a name, and, optionally, a description of the rule. For the filter criteria, you use specific attributes of findings to specify whether to include or exclude findings from a view. A *finding attribute* is a field that stores specific data for a finding, such as severity, type, or the name of the resource that a finding applies to. Filter criteria consist of one or more conditions. Each condition, also referred to as a *criterion*, consists of three parts:
+ An attribute-based field, such as **Severity** or **Finding type**.
+ An operator, such as *equals* or *not equals*.
+ One or more values. The type and number of values depends on the field and operator that you choose.

After you create and save a filter rule, you apply its filter criteria by choosing the rule. Macie then uses the criteria to determine which findings to display. Macie also displays the criteria to help you determine which criteria you applied.

Note that filter rules are different from suppression rules. A *suppression rule* is a set of filter criteria that you create and save to automatically archive findings that match the criteria of the rule. Although both types of rules store and apply filter criteria, a filter rule doesn't perform any action on findings that match the rule's criteria. Instead, a filter rule only determines which findings appear on the console after you apply the rule. For information about suppression rules, see [Suppressing findings](findings-suppression.md).

**To create a filter rule for findings**  
You can create a filter rule by using the Amazon Macie console or the Amazon Macie API.

------
#### [ Console ]

Follow these steps to create a filter rule by using the Amazon Macie console.

**To create a filter rule**

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**  
To use an existing filter rule as a starting point, choose the rule from the **Saved rules** list.  
You can also streamline creation of a rule by first pivoting and drilling down on findings by a predefined logical group. If you do this, Macie automatically creates and applies the appropriate filter conditions, which can be a helpful starting point for creating a rule. To do this, choose **By bucket**, **By type**, or **By job** in the navigation pane (under **Findings**). Then choose an item in the table. In the details panel, choose the link for the field to pivot on. 

1. In the **Filter criteria** box, add conditions that define the filter criteria for the rule.  
![\[The Filter criteria box on the Findings page.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-empty-conditions.png)

   To learn how to add filter conditions, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).

1. When you finish defining filter criteria for the rule, choose **Save rule** in the **Filter criteria** box.  
![\[The Save rule link in the Filter criteria box on the Findings page.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-save-rule.png)

1. Under **Filter rule**, enter a name and, optionally, a description of the rule.

1. Choose **Save**.

------
#### [ API ]

To create a filter rule programmatically, use the [CreateFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation of the Amazon Macie API and specify the appropriate values for the required parameters:
+ For the `action` parameter, specify `NOOP` to ensure that Macie doesn't suppress (automatically archive) findings that match the criteria of the rule.
+ For the `criterion` parameter, specify a map of conditions that define the filter criteria for the rule.

  In the map, each condition should specify a field, an operator, and one or more values for the field. The type and number of values depends on the field and operator that you choose. For information about the fields, operators, and types of values that you can use in a condition, see: [Fields for filtering Macie findings](findings-filter-fields.md), [Using operators in conditions](findings-filter-basics.md#findings-filter-basics-operators), and [Specifying values for fields](findings-filter-basics.md#findings-filter-basics-value-types).

To create a filter rule by using the AWS Command Line Interface (AWS CLI), run the [create-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/create-findings-filter.html) command and specify the appropriate values for the required parameters. The following examples create a filter rule that returns all sensitive data findings that are in the current AWS Region and report occurrences of personal information (and no other categories of sensitive data) in S3 objects.

This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.

```
$ aws macie2 create-findings-filter \
--action NOOP \
--name my_filter_rule \
--finding-criteria '{"criterion":{"classificationDetails.result.sensitiveData.category":{"eqExactMatch":["PERSONAL_INFORMATION"]}}}'
```

This example is formatted for Microsoft Windows and it uses the caret (^) line-continuation character to improve readability.

```
C:\> aws macie2 create-findings-filter ^
--action NOOP ^
--name my_filter_rule ^
--finding-criteria={\"criterion\":{\"classificationDetails.result.sensitiveData.category\":{\"eqExactMatch\":[\"PERSONAL_INFORMATION\"]}}}
```

Where:
+ *my\$1filter\$1rule* is the custom name for the rule.
+ `criterion` is a map of filter conditions for the rule:
  + *classificationDetails.result.sensitiveData.category* is the JSON name of the **Sensitive data category** field.
  + *eqExactMatch* specifies the *equals exact match* operator.
  + *PERSONAL\$1INFORMATION* is an enumerated value for the **Sensitive data category** field.

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/9b2b4508-aa2f-4940-b347-d1451example",
    "id": "9b2b4508-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the filter rule that was created, and `id` is the unique identifier for the rule.

For additional examples of filter criteria, see [Filtering findings programmatically with the Amazon Macie API](findings-filter-procedure.md#findings-filter-procedure-api).

------

# Applying a filter rule to Macie findings
<a name="findings-filter-rule-apply"></a>

When you apply a filter rule, Amazon Macie uses the rule's criteria to determine which findings to include or exclude from your view of findings on the console. Macie also displays the criteria to help you determine which criteria you applied.

**Tip**  
Although filter rules are designed for use with the Amazon Macie console, you can use a rule's criteria to query findings data programmatically with the Amazon Macie API. To do this, retrieve the filter criteria for the rule, and then add the criteria to your query. To retrieve the criteria, use the [GetFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters-id.html) operation. To then identify findings that match the criteria, use the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) operation and specify the criteria in your query. For information about specifying filter criteria in a query, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).

**To apply a filter rule to findings**

Follow these steps to filter findings on the Amazon Macie console by applying a filter rule.

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. In the **Saved rules** list, choose the filter rule that you want to apply. Macie applies the rule's criteria and displays the criteria in the **Filter criteria** box.

1. To refine the criteria, use the **Filter criteria** box to add or remove filter conditions. If you do this, your changes won't affect the settings for the rule. Macie saves your changes only if you explicitly save them as a new rule.

1. To apply a different filter rule, repeat step 3.

After you apply a filter rule, you can quickly remove all of its filter criteria from your view. To do this, choose the **X** in the **Filter criteria** box.

# Changing a filter rule for Macie findings
<a name="findings-filter-rule-change"></a>

After you create a filter rule, you can refine its criteria and change other settings for the rule. A *filter rule* is a set of filter criteria that you create and save to use again when you review findings on the Amazon Macie console. Filter rules can help you perform repeated, consistent analysis of findings that have specific characteristics. Each rule consists of a set of filter criteria, a name, and, optionally, a description. 

In addition to changing the filter criteria or other settings for a rule, you can assign tags to a rule. A *tag* is a label that you define and assign to certain types of AWS resources. Each tag consists of a required tag key and an optional tag value. Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. To learn more, see [Tagging Macie resources](tagging-resources.md).

**To change a filter rule for findings**  
To assign tags or change the settings for a filter rule, you can use the Amazon Macie console or the Amazon Macie API.

------
#### [ Console ]

Follow these steps to assign tags or change the settings for a filter rule by using the Amazon Macie console.

**To change a filter rule**

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. In the **Saved rules** list, choose the edit icon (![\[The edit icon, which is a blue pencil.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-edit-resource-blue.png)) next to the filter rule that you want to change or assign tags to. 

1. Do any of the following:
   + To change the filter criteria of the rule, use the **Filter criteria** box. In the box, enter conditions for the criteria that you want. To learn how, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).
   + To change the name of the rule, enter a new name in the **Name** box under **Filter rule**.
   + To change the description of the rule, enter a new description in the **Description** box under **Filter rule**. 
   + To assign tags to the rule, choose **Manage tags** under **Filter rule**. Then add, review, and change the tags as necessary. A rule can have as many as 50 tags.

1. When you finish making changes, choose **Save**.

------
#### [ API ]

To change a filter rule programmatically, use the [UpdateFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters-id.html) operation of the Amazon Macie API. When you submit your request, use the supported parameters to specify a new value for each setting that you want to change.

For the `id` parameter, specify the unique identifier for the rule to change. You can get this identifier by using the [ListFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation to retrieve a list of filter and suppression rules for your account. If you're using the AWS Command Line Interface (AWS CLI), run the [list-findings-filters](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings-filters.html) command to retrieve this list.

To change a filter rule by using the AWS CLI, run the [update-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/update-findings-filter.html) command and use the supported parameters to specify a new value for each setting that you want to change. For example, the following command changes the name of an existing filter rule.

```
C:\> aws macie2 update-findings-filter --id 9b2b4508-aa2f-4940-b347-d1451example --name personal_information_only
```

Where:
+ *9b2b4508-aa2f-4940-b347-d1451example* is the unique identifier for the rule.
+ *personal\$1information\$1only* is the new name for the rule.

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/9b2b4508-aa2f-4940-b347-d1451example",
    "id": "9b2b4508-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the rule that was changed, and `id` is the unique identifier for the rule.

Similarly, the following example converts a [suppression rule](findings-suppression.md) to a filter rule by changing the value for the `action` parameter from `ARCHIVE` to `NOOP`.

```
C:\> aws macie2 update-findings-filter --id 8a1c3508-aa2f-4940-b347-d1451example --action NOOP
```

Where:
+ *8a1c3508-aa2f-4940-b347-d1451example* is the unique identifier for the rule.
+ *NOOP* is the new action for Macie to perform on findings that match the criteria of the rule—perform no action (don't suppress the findings).

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/8a1c3508-aa2f-4940-b347-d1451example",
    "id": "8a1c3508-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the rule that was changed, and `id` is the unique identifier for the rule.

------

# Deleting a filter rule for Macie findings
<a name="findings-filter-rule-delete"></a>

If you create a filter rule, you can delete it at any time. A *filter rule* is a set of filter criteria that you create and save to use again when you review findings on the Amazon Macie console. If you delete a filter rule, your change doesn't affect findings that match the rule's criteria. A filter rule only determines which findings appear on the console after you apply the rule.

**To delete a filter rule for findings**  
You can delete a filter rule by using the Amazon Macie console or the Amazon Macie API.

------
#### [ Console ]

Follow these steps to delete a filter rule by using the Amazon Macie console.

**To delete a filter rule**

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. In the **Saved rules** list, choose the edit icon (![\[The edit icon, which is a blue pencil.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-edit-resource-blue.png)) next to the filter rule that you want to delete.

1. Under **Filter rule**, choose **Delete**.

------
#### [ API ]

To delete a filter rule programmatically, use the [DeleteFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters-id.html) operation of the Amazon Macie API. For the `id` parameter, specify the unique identifier for the filter rule to delete. You can get this identifier by using the [ListFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation to retrieve a list of filter and suppression rules for your account. If you're using the AWS Command Line Interface (AWS CLI), run the [list-findings-filters](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings-filters.html) command to retrieve this list.

To delete a filter rule by using the AWS CLI, run the [delete-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/delete-findings-filter.html) command. For example:

```
C:\> aws macie2 delete-findings-filter --id 9b2b4508-aa2f-4940-b347-d1451example
```

Where *9b2b4508-aa2f-4940-b347-d1451example* is the unique identifier for the filter rule to delete.

If the command runs successfully, Macie returns an empty HTTP 200 response. Otherwise, Macie returns an HTTP 4*xx* or 500 response that indicates why the operation failed.

------

# Investigating sensitive data with Macie findings
<a name="findings-investigate-sd"></a>

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
<a name="findings-locate-sd"></a>

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
<a name="findings-retrieve-sd"></a>

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
<a name="findings-retrieve-sd-options"></a>

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
<a name="findings-retrieve-sd-options-s3access"></a>

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
<a name="findings-retrieve-sd-options-s3access-user"></a>

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
<a name="findings-retrieve-sd-options-s3access-role"></a>

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
<a name="findings-retrieve-sd-options-s3access-role-configuration"></a>

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
<a name="findings-retrieve-sd-options-s3access-role-admin"></a>

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
<a name="findings-retrieve-sd-options-s3access-role-member"></a>

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
<a name="findings-retrieve-sd-options-s3access-role-standalone"></a>

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
<a name="findings-retrieve-sd-options-decrypt"></a>

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
<a name="findings-retrieve-sd-options-decrypt-same-account"></a>

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
<a name="findings-retrieve-sd-options-decrypt-cross-account"></a>

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": "<grant token>",
    "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2"
}
```

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

# Configuring Macie to retrieve sensitive data samples
<a name="findings-retrieve-sd-configure"></a>

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
<a name="findings-retrieve-sd-configure-prereqs"></a>

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
<a name="findings-retrieve-sd-configure-sddr"></a>

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
<a name="findings-retrieve-sd-configure-s3access"></a>

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
<a name="findings-retrieve-sd-configure-key"></a>

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
<a name="findings-retrieve-sd-configure-permissions"></a>

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
<a name="findings-retrieve-sd-configure-enable"></a>

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
<a name="findings-retrieve-sd-configure-manage"></a>

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
<a name="findings-retrieve-sd-proc"></a>

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
<a name="findings-retrieve-sd-proc-prereqs"></a>

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
<a name="findings-retrieve-sd-proc-criteria"></a>

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.<a name="findings-retrieve-sd-criteria-mimetype"></a>

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
<a name="findings-retrieve-sd-proc-steps"></a>

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
<a name="findings-locate-sd-schema"></a>

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
<a name="findings-locate-sd-schema-overview"></a>

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
<a name="findings-locate-sd-schema-examples"></a>

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
<a name="findings-locate-sd-schema-examples-cell"></a>

**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
<a name="findings-locate-sd-schema-examples-linerange"></a>

**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
<a name="findings-locate-sd-schema-examples-page"></a>

**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
<a name="findings-locate-sd-schema-examples-record"></a>

**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`.

# Suppressing Macie findings
<a name="findings-suppression"></a>

To streamline your analysis of findings, you can create and use suppression rules. A *suppression rule* is a set of attribute-based filter criteria that defines cases where you want Amazon Macie to archive findings automatically. Suppression rules are helpful in situations where you've reviewed a class of findings and don't want to be notified of them again.

For example, you might decide to allow S3 buckets to contain mailing addresses, if the buckets don't allow public access and they encrypt new objects automatically with a particular AWS KMS key. In this case, you can create a suppression rule that specifies filter criteria for the following fields: **Sensitive data detection type**, **S3 bucket public access permission**, and **S3 bucket encryption KMS key id**. The rule suppresses future findings that match the filter criteria.

If you suppress findings with a suppression rule, Macie continues to generate findings for subsequent occurrences of sensitive data and potential policy violations that match the rule's criteria. However, Macie automatically changes the status of the findings to *archived*. This means that the findings don't appear by default on the Amazon Macie console, but they persist in Macie until they expire. Macie stores findings for 90 days.

In addition, Macie doesn't publish suppressed findings to Amazon EventBridge as events or to AWS Security Hub CSPM. Macie does, however, continue to create and store [sensitive data discovery results](discovery-results-repository-s3.md) that correlate to sensitive data findings that you suppress. This helps ensure that you have an immutable history of sensitive data findings for data privacy and protection audits or investigations that you perform.

**Note**  
If your account is part of an organization that centrally manages multiple Macie accounts, suppression rules might work differently for your account. This depends on the category of findings that you want to suppress, and whether you have a Macie administrator or member account:  
**Policy findings** – Only a Macie administrator can suppress policy findings for the organization's accounts.  
If you have a Macie administrator account and you create a suppression rule, Macie applies the rule to policy findings for all the accounts in your organization unless you configure the rule to exclude specific accounts. If you have a member account and you want to suppress policy findings for your account, contact your Macie administrator.
**Sensitive data findings** – A Macie administrator and individual members can suppress sensitive data findings that their sensitive data discovery jobs produce. A Macie administrator can also suppress findings that Macie generates while performing automated sensitive data discovery for the organization.  
Only the account that creates a sensitive data discovery job can suppress or otherwise access sensitive data findings that the job produces. Only the Macie administrator account for an organization can suppress or otherwise access findings that automated sensitive data discovery produces for accounts in the organization.
For more information about the tasks that administrators and members can perform, see [Macie administrator and member account relationships](accounts-mgmt-relationships.md).

**Topics**
+ [Creating a suppression rule](findings-suppression-rule-create.md)
+ [Reviewing suppressed findings](findings-suppression-view-findings.md)
+ [Changing a suppression rule](findings-suppression-rule-change.md)
+ [Deleting a suppression rule](findings-suppression-rule-delete.md)

# Creating a suppression rule for Macie findings
<a name="findings-suppression-rule-create"></a>

A *suppression rule* is a set of attribute-based filter criteria that defines cases where you want Amazon Macie to archive findings automatically. Suppression rules are helpful in situations where you've reviewed a class of findings and don't want to be notified of them again. When you create a suppression rule, you specify filter criteria, a name, and, optionally, a description of the rule. Macie then uses the rule's criteria to determine which findings to archive automatically. By using suppression rules, you can streamline your analysis of findings.

If you suppress findings with a suppression rule, Macie continues to generate findings for subsequent occurrences of sensitive data and potential policy violations that match the rule's criteria. However, Macie automatically changes the status of the findings to *archived*. This means that the findings don't appear by default on the Amazon Macie console, but they persist in Macie until they expire. (Macie stores findings for 90 days.) This also means that Macie doesn't publish the findings to Amazon EventBridge as events or to AWS Security Hub CSPM.

Note that suppression rules might work differently for your account, if your account is part of an organization that centrally manages multiple Macie accounts. This depends on the category of findings that you want to suppress, and whether you have a Macie administrator or member account:
+ **Policy findings** – Only a Macie administrator can suppress policy findings for the organization's accounts.

  If you have a Macie administrator account and you create a suppression rule, Macie applies the rule to policy findings for all the accounts in your organization unless you configure the rule to exclude specific accounts. If you have a member account and you want to suppress policy findings for your account, work with your Macie administrator to suppress the findings.
+ **Sensitive data findings** – A Macie administrator and individual members can suppress sensitive data findings that their sensitive data discovery jobs produce. A Macie administrator can also suppress findings that Macie generates while performing automated sensitive data discovery for the organization.

  Only the account that creates a sensitive data discovery job can suppress or otherwise access sensitive data findings that the job produces. Only the Macie administrator account for an organization can suppress or otherwise access findings that automated sensitive data discovery produces for accounts in the organization.

For more information about the tasks that administrators and members can perform, see [Macie administrator and member account relationships](accounts-mgmt-relationships.md).

Also note that suppression rules are different from filter rules. A *filter rule* is a set of filter criteria that you create and save to use again when you review findings on the Amazon Macie console. Although both types of rules store and apply filter criteria, a filter rule doesn't perform any action on findings that match the rule's criteria. Instead, a filter rule only determines which findings appear on the console after you apply the rule. For more information, see [Defining filter rules](findings-filter-rule-procedures.md). Depending on your analysis goals, you might determine that it's best to create a filter rule instead of a suppression rule.

**To create a suppression rule for findings**  
You can create a suppression rule by using the Amazon Macie console or the Amazon Macie API. Before you create a suppression rule, it's important to note that you can't restore (unarchive) findings that you suppress using a suppression rule. You can, however, [review suppressed findings](findings-suppression-view-findings.md) by using Macie.

------
#### [ Console ]

Follow these steps to create a suppression rule by using the Amazon Macie console.

**To create a suppression rule**

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**  
To use an existing suppression or filter rule as a starting point, choose the rule from the **Saved rules** list.  
You can also streamline creation of a rule by first pivoting and drilling down on findings by a predefined logical group. If you do this, Macie automatically creates and applies the appropriate filter conditions, which can be a helpful starting point for creating a rule. To do this, choose **By bucket**, **By type**, or **By job** in the navigation pane (under **Findings**). Then choose an item in the table. In the details panel, choose the link for the field to pivot on. 

1. In the **Filter criteria** box, add filter conditions that specify attributes of the findings that you want the rule to suppress.  
![\[The Filter criteria box on the Findings page.\]](http://docs.aws.amazon.com/macie/latest/user/images/scrn-findings-filter-bar-empty-conditions.png)

   To learn how to add filter conditions, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).

1. When you finish adding filter conditions for the rule, choose **Suppress findings**.

1. Under **Suppression rule**, enter a name and, optionally, a description of the rule.

1. Choose **Save**.

------
#### [ API ]

To create a suppression rule programmatically, use the [CreateFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation of the Amazon Macie API and specify the appropriate values for the required parameters:
+ For the `action` parameter, specify `ARCHIVE` to ensure that Macie suppresses findings that match the criteria of the rule.
+ For the `criterion` parameter, specify a map of conditions that define the filter criteria for the rule.

  In the map, each condition should specify a field, an operator, and one or more values for the field. The type and number of values depends on the field and operator that you choose. For information about the fields, operators, and types of values that you can use in a condition, see: [Fields for filtering Macie findings](findings-filter-fields.md), [Using operators in conditions](findings-filter-basics.md#findings-filter-basics-operators), and [Specifying values for fields](findings-filter-basics.md#findings-filter-basics-value-types).

To create a suppression rule by using the AWS Command Line Interface (AWS CLI), run the [create-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/create-findings-filter.html) command and specify the appropriate values for the required parameters. The following examples create a suppression rule that returns all sensitive data findings that are in the current AWS Region and report occurrences of mailing addresses (and no other types of sensitive data) in S3 objects.

This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.

```
$ aws macie2 create-findings-filter \
--action ARCHIVE \
--name my_suppression_rule \
--finding-criteria '{"criterion":{"classificationDetails.result.sensitiveData.detections.type":{"eqExactMatch":["ADDRESS"]}}}'
```

This example is formatted for Microsoft Windows and it uses the caret (^) line-continuation character to improve readability.

```
C:\> aws macie2 create-findings-filter ^
--action ARCHIVE ^
--name my_suppression_rule ^
--finding-criteria={\"criterion\":{\"classificationDetails.result.sensitiveData.detections.type\":{\"eqExactMatch\":[\"ADDRESS\"]}}}
```

Where:
+ *my\$1suppression\$1rule* is the custom name for the rule.
+ `criterion` is a map of filter conditions for the rule:
  + *classificationDetails.result.sensitiveData.detections.type* is the JSON name of the **Sensitive data detection type** field.
  + *eqExactMatch* specifies the *equals exact match* operator.
  + *ADDRESS* is an enumerated value for the **Sensitive data detection type** field.

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/8a3c5608-aa2f-4940-b347-d1451example",
    "id": "8a3c5608-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the suppression rule that was created, and `id` is the unique identifier for the rule.

For additional examples of filter criteria, see [Filtering findings programmatically with the Amazon Macie API](findings-filter-procedure.md#findings-filter-procedure-api).

------

# Reviewing suppressed findings in Macie
<a name="findings-suppression-view-findings"></a>

If you suppress findings with a suppression rule, Amazon Macie continues to generate findings for subsequent occurrences of sensitive data and potential policy violations that match the rule's criteria. However, Macie automatically changes the status of the findings to *archived*. This means that the findings don't appear by default on the Amazon Macie console, but they persist in Macie until they expire. (Macie stores findings for 90 days.) This also means that Macie doesn't publish the findings to Amazon EventBridge as events or to AWS Security Hub CSPM.

Because suppressed findings persist in Macie for up to 90 days, you can access and review them before they expire. In addition to broadening your analysis of findings, this can help you determine whether to adjust your suppression criteria. To adjust the criteria, [change the suppression rules](findings-suppression-rule-change.md) for your account. 

You can review suppressed findings on the Amazon Macie console by changing your filter settings.

**To review suppressed findings on the console**

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**. The **Findings** page displays findings that Macie created or updated for your account in the current AWS Region during the past 90 days. By default, this doesn't include findings that were suppressed by a suppression rule.

1. To pivot on and review the findings by a predefined logical group, choose **By bucket**, **By type**, or **By job** in the navigation pane (under **Findings**).

1. For **Finding status**, do one of the following:
   + To display only suppressed findings, choose **Archived**.
   + To display both suppressed and unsuppressed findings, choose **All**.
   + To hide suppressed findings again, choose **Current**.

You can also access suppressed findings by using the Amazon Macie API. To retrieve a list of suppressed findings, use the [ListFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings.html) operation. In your request, include a filter condition that specifies `true` for the `archived` field. For an example of how to do this by using the AWS Command Line Interface (AWS CLI), see [Filtering findings programmatically](findings-filter-procedure.md#findings-filter-procedure-api). To then retrieve the details of one or more suppressed findings, use the [GetFindings](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html) operation. In your request, specify the unique identifier for each finding to retrieve.

**Note**  
As you review the findings, note that suppression rules can work differently for accounts that are part of an organization. This depends on a finding's category and whether you have a Macie administrator or member account:  
**Policy findings** – Only a Macie administrator can suppress policy findings for the organization's accounts.  
If you have a Macie administrator account and you created a suppression rule, Macie applies the rule to policy findings for all the accounts in your organization unless you configured the rule to exclude specific accounts. If you have a member account and you want to suppress policy findings for your account, work with your Macie administrator to suppress the findings.
**Sensitive data findings** – A Macie administrator and individual members can suppress sensitive data findings that their sensitive data discovery jobs produce. A Macie administrator can also suppress findings that Macie generates while performing automated sensitive data discovery for the organization.  
Only the account that creates a sensitive data discovery job can suppress or otherwise access sensitive data findings that the job produces. Only the Macie administrator account for an organization can suppress or otherwise access findings that automated sensitive data discovery produces for accounts in the organization.
For more information about the tasks that administrators and members can perform, see [Macie administrator and member account relationships](accounts-mgmt-relationships.md).

# Changing a suppression rule for Macie findings
<a name="findings-suppression-rule-change"></a>

After you create a suppression rule, you can change the settings for the rule. A *suppression rule* is a set of attribute-based filter criteria that defines cases where you want Amazon Macie to archive findings automatically. Suppression rules are helpful in situations where you've reviewed a class of findings and don't want to be notified of them again. Each rule consists of a set of filter criteria, a name, and, optionally, a description.

If you change the criteria of a suppression rule, findings that were previously suppressed by the rule continue to be suppressed. The findings continue to have a status of *archived* and Macie doesn't publish them to Amazon EventBridge or AWS Security Hub CSPM. Macie applies the new criteria only to new sensitive data findings, new policy findings, and subsequent occurrences of existing policy findings.

In addition to changing the criteria or other settings for a rule, you can assign tags to a rule. A *tag* is a label that you define and assign to certain types of AWS resources. Each tag consists of a required tag key and an optional tag value. Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. To learn more, see [Tagging Macie resources](tagging-resources.md).

**To change a suppression rule for findings**  
To assign tags or change the settings for a suppression rule, you can use the Amazon Macie console or the Amazon Macie API.

------
#### [ Console ]

Follow these steps to assign tags or change the settings for a suppression rule by using the Amazon Macie console.

**To change a suppression rule**

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. In the **Saved rules** list, choose the edit icon (![\[The edit icon, which is a blue pencil.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-edit-resource-blue.png)) next to the suppression rule that you want to change or assign tags to. 

1. Do any of the following:
   + To change the criteria of the rule, use the **Filter criteria** box. In the box, enter conditions that specify attributes of the findings that you want the rule to suppress. To learn how, see [Creating and applying filters to Macie findings](findings-filter-procedure.md).
   + To change the name of the rule, enter a new name in the **Name** box under **Suppression rule**.
   + To change the description of the rule, enter a new description in the **Description** box under **Suppression rule**.
   + To assign tags to the rule, choose **Manage tags** under **Suppression rule**. Then add, review, and change the tags as necessary. A rule can have as many as 50 tags.

1. When you finish making changes, choose **Save**.

------
#### [ API ]

To change a suppression rule programmatically, use the [UpdateFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters-id.html) operation of the Amazon Macie API. When you submit your request, use the supported parameters to specify a new value for each setting that you want to change.

For the `id` parameter, specify the unique identifier for the rule to change. You can get this identifier by using the [ListFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation to retrieve a list of suppression and filter rules for your account. If you're using the AWS Command Line Interface (AWS CLI), run the [list-findings-filters](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings-filters.html) command to retrieve this list.

To change a suppression rule by using the AWS CLI, run the [update-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/update-findings-filter.html) command and use the supported parameters to specify a new value for each setting that you want to change. For example, the following command changes the name of an existing suppression rule.

```
C:\> aws macie2 update-findings-filter --id 8a3c5608-aa2f-4940-b347-d1451example --name mailing_addresses_only
```

Where:
+ *8a3c5608-aa2f-4940-b347-d1451example* is the unique identifier for the rule.
+ *mailing\$1addresses\$1only* is the new name for the rule.

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/8a3c5608-aa2f-4940-b347-d1451example",
    "id": "8a3c5608-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the rule that was changed, and `id` is the unique identifier for the rule.

Similarly, the following example converts a [filter rule](findings-filter-rule-procedures.md) to a suppression rule by changing the value for the `action` parameter from `NOOP` to `ARCHIVE`.

```
C:\> aws macie2 update-findings-filter --id 8a1c3508-aa2f-4940-b347-d1451example --action ARCHIVE
```

Where:
+ *8a1c3508-aa2f-4940-b347-d1451example* is the unique identifier for the rule.
+ *ARCHIVE* is the new action for Macie to perform on findings that match the criteria of the rule—suppress the findings.

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

```
{
    "arn": "arn:aws:macie2:us-west-2:123456789012:findings-filter/8a1c3508-aa2f-4940-b347-d1451example",
    "id": "8a1c3508-aa2f-4940-b347-d1451example"
}
```

Where `arn` is the Amazon Resource Name (ARN) of the rule that was changed, and `id` is the unique identifier for the rule.

------

# Deleting a suppression rule for Macie findings
<a name="findings-suppression-rule-delete"></a>

You can delete a suppression rule at any time. If you delete a suppression rule, Amazon Macie stops suppressing new and subsequent occurrences of findings that match the rule's criteria and aren't suppressed by other rules. Note, however, that Macie might continue to suppress findings that it's currently processing and match the rule's criteria.

After you delete a suppression rule, new and subsequent occurrences of findings that match the rule's criteria have a status of *current* (not *archived*). This means that they appear by default on the Amazon Macie console. In addition, Macie publishes them to Amazon EventBridge as events. Depending on the [publication settings](findings-publish-frequency.md) for your account, Macie also publishes the findings to AWS Security Hub CSPM.

**To delete a suppression rule for findings**  
You can delete a suppression rule by using the Amazon Macie console or the Amazon Macie API.

------
#### [ Console ]

Follow these steps to delete a suppression rule by using the Amazon Macie console.

**To delete a suppression rule**

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. In the **Saved rules** list, choose the edit icon (![\[The edit icon, which is a blue pencil.\]](http://docs.aws.amazon.com/macie/latest/user/images/icon-edit-resource-blue.png)) next to the suppression rule that you want to delete.

1. Under **Suppression rule**, choose **Delete**.

------
#### [ API ]

To delete a suppression rule programmatically, use the [DeleteFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters-id.html) operation of the Amazon Macie API. For the `id` parameter, specify the unique identifier for the suppression rule to delete. You can get this identifier by using the [ListFindingsFilter](https://docs.aws.amazon.com/macie/latest/APIReference/findingsfilters.html) operation to retrieve a list of suppression and filter rules for your account. If you're using the AWS Command Line Interface (AWS CLI), run the [list-findings-filters](https://docs.aws.amazon.com/cli/latest/reference/macie2/list-findings-filters.html) command to retrieve this list.

To delete a suppression rule by using the AWS CLI, run the [delete-findings-filter](https://docs.aws.amazon.com/cli/latest/reference/macie2/delete-findings-filter.html) command. For example:

```
C:\> aws macie2 delete-findings-filter --id 8a3c5608-aa2f-4940-b347-d1451example
```

Where *8a3c5608-aa2f-4940-b347-d1451example* is the unique identifier for the suppression rule to delete.

If the command runs successfully, Macie returns an empty HTTP 200 response. Otherwise, Macie returns an HTTP 4*xx* or 500 response that indicates why the operation failed.

------