Creating and managing filter rules for findings

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 consistent analysis of findings that have specific characteristics. For example, you might create one filter rule for analyzing all high-severity policy findings for S3 buckets that contain unencrypted objects, and another filter rule for analyzing all high-severity sensitive data findings that report specific types of sensitive data.

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 criteria of the rule. 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.

To create and manage filter rules, you can use the Amazon Macie console or the Amazon Macie API. The following topics explain how. For the API, the topics include examples of how to perform these tasks using the AWS Command Line Interface (AWS CLI). You can also perform these tasks 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.

Creating filter rules

When you create a filter rule, you specify filter criteria, a name, and, optionally, a description of the rule. 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/.

2. 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), and then choose an item in the table. In the details panel, choose the link for the field to pivot on.

3. In the filter bar, add conditions that define the filter criteria for the rule. To learn how, see Creating and applying filters to findings.

4. When you finish defining filter criteria for the rule, choose Save rule in the filter bar.

   

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

6. Choose Save.

API

To create a filter rule programmatically, use the CreateFindingsFilter 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 findings, Using operators in conditions, and Specifying values for fields.

To create a filter rule by using the AWS CLI, run the create-findings-filter 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 (\) 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_filter_rule 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_INFORMATION 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.

Applying filter rules

When you apply a filter rule, Macie uses the criteria of the rule to determine which findings to include or exclude from your view of findings on the console. Macie also displays the criteria in the filter bar.

Note that filter rules are designed for use with the Amazon Macie console. You can't use them directly in queries that you submit programmatically using the Amazon Macie API. However, if you're using the API to query findings, you can retrieve the filter criteria for a rule by using the GetFindingsFilter operation. You can then add the criteria to your query. For information about specifying filter criteria in a query, see Creating and applying filters to findings.

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

To apply a filter rule

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

2. In the navigation pane, choose Findings.

3. In the Saved rules list, choose the filter rule that you want to apply. Macie applies the criteria of the rule and displays the criteria in the filter bar.

4. (Optional) To refine the criteria, use the filter bar to add or remove filter conditions. If you do this, your changes won't affect the settings for the rule. Macie won't save any of your changes unless you explicitly save them as a new rule.

5. 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 by choosing the X in the filter bar.

Changing filter rules

You can change the settings for a filter rule at any time by using the Amazon Macie console or the Amazon Macie API. You can also assign and manage tags for the 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 Amazon Macie resources.

Console

Follow these steps to change the settings for an existing 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/.

2. In the navigation pane, choose Findings.

3. In the Saved rules list, choose the edit icon ( ) next to the filter rule that you want to change.

4. Do any of the following:

   • To change the filter criteria of the rule, use the filter bar to enter conditions for the criteria that you want. To learn how, see Creating and applying filters to findings.

   • 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, review, or edit tags for the rule, choose Manage tags under Filter rule. Then review and change the tags as necessary. A rule can have as many as 50 tags.

5. When you finish making changes, choose Save.

API

To change a filter rule programmatically, use the UpdateFindingsFilter 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 operation to retrieve a list of filter and suppression rules for your account. If you're using the AWS CLI, run the list-findings-filters command to retrieve this list.

To change a filter rule by using the AWS CLI, run the update-findings-filter 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_information_only 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 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 filter rules

You can delete a filter rule at any time 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/.

2. In the navigation pane, choose Findings.

3. In the Saved rules list, choose the edit icon ( ) next to the filter rule that you want to delete.

4. Under Filter rule, choose Delete.

API

To delete a filter rule programmatically, use the DeleteFindingsFilter 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 operation to retrieve a list of filter and suppression rules for your account. If you're using the AWS CLI, run the list-findings-filters command to retrieve this list.

To delete a filter rule by using the AWS CLI, run the delete-findings-filter 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 4xx or 500 response that indicates why the operation failed.