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
Open the Amazon Macie console at https://console.aws.amazon.com/macie/.
-
In the navigation pane, choose Findings.
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.
-
In the filter bar, add conditions that define the filter criteria for the rule.
To learn how, see Creating and applying filters to findings.
-
When you finish defining filter criteria for the rule, choose Save
rule in the filter bar.
-
Under Filter rule, enter a name and, optionally, a
description of the rule.
-
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:
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
Open the Amazon Macie console at https://console.aws.amazon.com/macie/.
-
In the navigation pane, choose Findings.
-
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.
-
(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.
-
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
Open the Amazon Macie console at https://console.aws.amazon.com/macie/.
-
In the navigation pane, choose Findings.
-
In the Saved rules list, choose the edit icon
(
) next to the filter rule that you want to change.
-
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.
-
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:
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
Open the Amazon Macie console at https://console.aws.amazon.com/macie/.
-
In the navigation pane, choose Findings.
-
In the Saved rules list, choose the edit icon
(
) next to the filter rule that you want to delete.
-
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.