Creating and applying filters to findings - Amazon Macie

Creating and applying filters to 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 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.

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

Filtering findings on 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 the filter bar on Findings pages, as shown in the following image.


        The filter bar above the table on the Findings page.

When you place your cursor in the filter bar, 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 box in the filter bar, as shown in the following image.


        The filter bar, above the table on the Findings page, with a
          filter box for a condition.

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 ( A solid, dark gray circle ) in a filter box. If you do this, Macie changes the operator to not equals and displays the not equals icon ( An empty, dark gray circle with a backslash ) in the filter box. 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 the filter bar. You can refer to the filter bar at any time to see which criteria you've applied. To remove a condition, choose the remove condition icon ( A circle with an X in it ) in the filter box for the condition.

To filter findings using the console

  1. Open the Amazon Macie console at https://console.aws.amazon.com/macie/.

  2. In the navigation pane, choose Findings.

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

  4. (Optional) To display findings that were suppressed by a suppression rule, choose Current in the filter bar. Then choose Archived to display only suppressed findings, or choose All to display both current and suppressed findings.

  5. To add a filter condition:

    1. Place your cursor in the filter bar, and then choose the field to use for the condition. For information about the fields that you can use, see Fields for filtering findings.

    2. Enter the appropriate type of value for the field. For detailed information about the different types of values, see Specifying values for fields.

      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.

    3. When you finish adding values for the field, choose Apply. Macie applies the filter criteria and adds the condition to a filter box in the filter bar.

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

  7. To remove a condition, choose the remove condition icon ( A circle with an X in it ) in the filter box for the condition.

  8. To change a condition, remove the condition by choosing the remove condition icon ( A circle with an X in it ) in the filter box for the condition. Then repeat step 5 to add a condition with the correct settings.

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

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 Findings Filters resource 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 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 sending HTTPS requests directly to Macie, or by using a current version of another AWS command line tool or an AWS SDK. 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 uses the list-findings command to retrieve finding IDs for all of your 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

This example uses the list-findings command to retrieve finding IDs for all of your sensitive data findings that are in the current Region and report occurrences of financial data (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:

  • classificationDetails.result.sensitiveData.category specifies the JSON name of the Sensitive data category field.

  • eqExactMatch specifies the equals exact match operator.

  • FINANCIAL_INFORMATION is an enumerated value for the Sensitive data category field.

Example 3: Filter findings based on a fixed time range

This example uses the list-findings command to retrieve finding IDs for all of your 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

This example uses the list-findings command to retrieve finding IDs for all of your 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

This example uses the list-findings command to retrieve finding IDs for all of your 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:

  • 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_INFORMATION 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.