Creating and applying filters to Macie findings

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:

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

Filtering findings by using the Amazon Macie console

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.

By using the Finding status menu, you can specify whether to include findings that were suppressed (automatically archived) by a suppression rule. 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.

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.

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 ( ) in the token for the condition.

Filtering findings programmatically with the Amazon Macie API

To filter findings programmatically, specify filter criteria in queries that you submit using the ListFindings or GetFindingStatistics 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. 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 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, Using operators in conditions, and Specifying values for fields.

The following examples show you how to specify filter criteria in queries that you submit using the AWS Command Line Interface (AWS CLI). 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.

The examples use the list-findings 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

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:

Example 2: Filter findings based on sensitive data category

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 (\) 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:

Example 3: Filter findings based on a fixed time range

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:

Example 4: Filter findings based on suppression status

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:

Example 5: Filter findings based on multiple fields and types of values

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 (\) 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: