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 view 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 meet the criteria of a rule. Although both types of rules store and
apply filter
criteria, a filter rule doesn't perform any action on findings that meet the criteria
of a 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 explain how to perform these
tasks
with the AWS Command Line Interface
(AWS CLI). You can also perform these tasks 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.
Creating filter rules
When you create a filter rule, you specify filter criteria, a name, and, optionally,
a
description for the rule. You can create a filter rule 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 for the rule.
-
Choose Save.
- AWS CLI
-
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. For the action parameter, specify NOOP to
ensure that Macie doesn't suppress (automatically archive) findings that meet 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.
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 of the API, and 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 using the Amazon Macie console
or
the Amazon Macie API.
- 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 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 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.
-
When you finish making changes, choose Save.
- AWS CLI
-
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 the id parameter,
specify the unique identifier for the rule to change. You can get this identifier
by
running the list-findings-filters command to retrieve a list of filter and suppression
rules for your account.
The following example 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 meet 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 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.
- AWS CLI
-
To delete a filter rule by using the AWS CLI, run the delete-findings-filter command. For the id parameter, specify
the unique identifier for the filter rule to delete. You can get this identifier by
running the list-findings-filters command to retrieve a list of filter and suppression
rules for your account.
The following example deletes the filter rule whose unique identifier is
9b2b4508-aa2f-4940-b347-d1451example.
C:\> aws macie2 delete-findings-filter --id 9b2b4508-aa2f-4940-b347-d1451example
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.
