AWS guardduty documentation change
Summary
Added documentation for creating/saving filters using API/CLI with examples, clarified severity level mappings, and noted console/API behavior differences
Security assessment
The changes document security feature usage (finding filters in GuardDuty) but do not address a specific vulnerability. The note about console/API filter behavior differences is a usability clarification rather than a security fix.
Diff
diff --git a/guardduty/latest/ug/guardduty_filter-findings.md b/guardduty/latest/ug/guardduty_filter-findings.md index 06ff20812..ad9364fed 100644 --- a/guardduty/latest/ug/guardduty_filter-findings.md +++ b/guardduty/latest/ug/guardduty_filter-findings.md @@ -5 +5 @@ -Creating and saving filter set in the GuardDuty consoleProperty filters in GuardDuty +Creating and saving filter set in the GuardDuty consoleCreating and saving filter set by using GuardDuty API and CLIProperty filters in GuardDuty @@ -11,5 +11 @@ A finding filter allows you to view findings that match the criteria you specify -## Creating and saving filter set in the GuardDuty console - -Finding filters can be created and tested through the GuardDuty console. You can save filters created through the console for use in suppression rules or future filter operations. A filter is made up of at least one filter criteria, which consists of one filter attribute paired with at least one value. - -When you create filters, be aware of the following: +When you create filters, take the following list into consideration: @@ -24,0 +21,2 @@ When you create filters, be aware of the following: + * For information about the maximum number of saved filters that you can create in an AWS account in each AWS Region, see [GuardDuty quotas](./guardduty_limits.html). + @@ -27,0 +26,6 @@ When you create filters, be aware of the following: +The following sections provide instructions on how to create and save filters using GuardDuty console, and API and CLI commands. Choose your preferred access method to proceed. + +## Creating and saving filter set in the GuardDuty console + +Finding filters can be created and tested through the GuardDuty console. You can save filters created through the console for use in suppression rules or future filter operations. A filter is made up of at least one filter criteria, which consists of one filter attribute paired with at least one value. + @@ -74,0 +79,55 @@ To apply this filter combination again in the future, you can save the specified +## Creating and saving filter set by using GuardDuty API and CLI + +You can create and test the finding filters by using either API or CLI commands. A filter is made up of at least one filter criteria, which consists of one filter attribute paired with at least one value. You can save filters to create [Suppression rules](./findings_suppression-rule.html) or to perform other filter operations later. + +###### To create finding filters using API/CLI + + * Run [CreateFilter](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_CreateFilter.html) API by using the regional detector ID of the AWS account where you want to create a filter. + +To find the `detectorId` for your account and current Region, see the **Settings** page in the [https://console.aws.amazon.com/guardduty/](https://console.aws.amazon.com/guardduty/) console, or run the [ListDetectors](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html) API. + + * Alternatively, you can use the [create-filter](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/guardduty/create-filter.html) CLI to create and save the filter. You can use one or more filter criteria from Property filters in GuardDuty. + +Use the following examples by replacing the placeholder values shown in red. + +**Example 1** : Create a new filter to view all the findings that match a specific finding type + + +The following example creates a filter that matches all `PortScan` findings for an instance created from a specific image. The placeholder values are shown in red. Replace these values with suitable values for your account. For example, replace `12abc34d567e8fa901bc2d34EXAMPLE` with your regional detector ID. + + aws guardduty create-filter \ + --detector-id 12abc34d567e8fa901bc2d34EXAMPLE \ + --name FilterExampleName \ + --finding-criteria '{"Criterion": {"type": {"Equals": ["Recon:EC2/Portscan"]}, "resource.instanceDetails.imageId": {"Equals":["ami-0a7a207083example"]}} }' + +**Example 2** : Create a new filter to view all the findings that match severity levels + + +The following example creates a filter that matches all findings associated with the `HIGH` severity levels. The placeholder values are shown in red. Replace these values with suitable values for your account. For example, replace `12abc34d567e8fa901bc2d34EXAMPLE` with your regional detector ID. + + aws guardduty create-filter \ + --detector-id 12abc34d567e8fa901bc2d34EXAMPLE \ + --name FilterExampleName \ + --finding-criteria '{"Criterion": {"severity": {"Equals": ["7", "8"]}} }' + + * For API/CLI, the [Findings severity levels](./guardduty_findings-severity.html) are represented as numerals. To filter the findings based on the severity levels, use the following values: + + * For `LOW` severity levels, use `{ "severity": { "Equals": ["1", "2", "3"] } }` + + * For `MEDIUM` severity levels, use `{ "severity": { "Equals": ["4", "5", "6"] } }` + + * For `HIGH` severity levels, use `{ "severity": { "Equals": ["7", "8"] } }` + + * For `CRITICAL` severity levels, use `{ "severity": { "Equals": ["9", "10"] } }` + + * For findings with multiple severity levels, use placeholder values similar to the following example: `{ "severity": { "Equals": ["7", "8", "9", "10"] } }` + +This example will show the findings that have either `HIGH` or `CRITICAL` severity levels. + +###### Note + +If you specify an example with only one numeric value instead of all the numeric values associated with a severity level, the API and CLI might show the filtered findings. When you use this saved filter set in the GuardDuty console, it will not work as expected. This is because the GuardDuty console considers the filter values as `CRITICAL`, `HIGH`, `MEDIUM`, and `LOW`. For example, a filter created with a CLI command that includes `{ "severity": { "Equals": ["9"] } }` is expected to show an appropriate output in API/CLI. However, this saved filter includes partial severity level when used in the GuardDuty console and will not show an expected output. This makes it necessary for the API and CLI to specify all the values associated with each severity level. + + + +