Managing and reviewing finding details and history

There are multiple ways to view finding lists on the AWS Security Hub console:

• Findings page – Displays a comprehensive list of findings from all enabled controls and product integrations. By default, active findings with a NEW or NOTIFIED workflow status are shown.

• Control details page – Displays a list of findings that were generated in the last 24 hours for a specific control.

• Insights page – Displays a list of findings for a matching insight. An insight is a collection specific findings. For more information, see Viewing and taking action on insight results and findings.

• Integrations page – Displays a list of findings generated by an integrated AWS service or third-party product.

You can filter and group findings on these lists to focus on specific types of findings. You can also select a specific finding on the preceding pages to view details about it.

To view a list of findings programmatically, use the GetFindings operation of the Security Hub API. You can include filters to retrieve specific types of findings.

If you enable cross-Region aggregation, you can retrieve control statuses, security scores, insights, and findings from across Regions. In the aggregation Region, finding data includes data from the aggregation Region and the linked Regions. In other Regions, finding data is specific to that Region only. For information about configuring cross-Region aggregation, see Cross-Region aggregation.

Filtering and grouping findings (console)

When you display a list of findings on the Findings page, Integrations page, or Insights page of the Security Hub console, the list is pre-filtered based on the record state and workflow status. This is in addition to the filters for an insight or integration.

Record state indicates whether a finding is active or archived. By default, a finding list only shows active findings.A finding can be archived by the finding provider. AWS Security Hub also automatically archives control findings if the associated resource is deleted.

Workflow status indicates the status of an investigation into a finding. By default, a finding list only shows findings with a workflow status of NEW or NOTIFIED. You can update the workflow status of a finding.

If you enabled finding aggregation and are signed in to the aggregation Region, you can filter findings by Region on the Findings and Insights pages.

For information about working with control findings, see Filtering, sorting, and downloading control findings. The information on this page applies to finding lists on the Findings, Insights, and Integrations pages.

Adding filters

To change the scope of the list, you can add filters to it.

You can filter by up to 10 attributes. For each attribute, you can provide up to 20 filter values.

When filtering the finding list, Security Hub applies AND logic to the set of filters. In other words, a finding only matches if it matches all of the provided filters. For example, if you add GuardDuty as a filter for product name, and AwsS3Bucket as a filter for resource type, then matching findings must match both of these criteria.

However, Security Hub applies OR logic to filters that use the same attribute but different values. For example, you add both GuardDuty and Amazon Inspector as filter values for product name. In that case, a finding matches if it was generated by either GuardDuty or Amazon Inspector.

To add a filter to the finding list

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

2. To display a finding list, do one of the following:

   • In the Security Hub navigation pane, choose Findings.

   • In the Security Hub navigation pane, choose Insights. Choose an insight. Then on the results list, choose an insight result.

   • In the Security Hub navigation pane, choose Integrations. Choose See findings for an integration.

3. In the Add filters box, for Filters, choose a filter.

   When you filter by Company name or Product name, the console uses the top-level CompanyName and ProductName fields. The API uses the values that are in ProductFields.

4. Choose the filter match type.

   For a string filter, you can choose from the following comparison options:

   • is – Find a value that exactly matches the filter value.

   • starts with – Find a value that starts with the filter value.

   • is not – Find a value that does not match the filter value.

   • does not start with – Find a value that does not start with the filter value.

   For a numeric filter, you can choose whether to provide a single number (Simple) or a range of numbers (Range).

   For a date or time filter, you can choose whether to provide a length of time from the current date and time (Rolling window) or a specific date range (Fixed range).

   Adding multiple filters has the following interactions:

   • is and starts with filters are joined by OR. A value matches if it contains any of the filter values. For example, if you specify Severity label is CRITICAL and Severity label is HIGH, the results include both critical and high severity findings.

   • is not and does not start with filters are joined by AND. A value matches only if it does not contain any of those filter values. For example, if you specify Severity label is not LOW and Severity label is not MEDIUM, the results don't include low or medium severity findings.

   If you have an is filter on a field, you can't have an is not or a does not start with filter on the same field.

5. Specify the filter value.

   For string filters, the filter value is case sensitive.

   For example, for findings from Security Hub, Product name is Security Hub. If you use the EQUALS operator to see findings from Security Hub, you must enter Security Hub as the filter value. If you enter security hub, no findings are displayed.

   Similarly, if you use the PREFIX operator, and enter Sec, Security Hub findings are displayed. If you enter sec, no Security Hub findings are displayed.

6. Choose Apply.

Grouping findings

In addition to changing the filters, you can group the findings based on the values of a selected attribute.

When you group the findings, the list of findings is replaced with a list of values for the selected attribute in the matching findings. For each value, the list displays the number of findings that match the other filter criteria.

For example, if you group the findings by AWS account ID, you see a list of account identifiers, with the number of matching findings for each account.

Note that Security Hub can only display 100 values. If there are more than 100 grouping values, you only see the first 100.

When you choose an attribute value, the list of matching findings for that value is displayed.

To group the findings in a findings list

1. On the finding list, choose the Add filters box.

2. For Grouping, choose Group by.

3. In the list, choose the attribute to use for the grouping.

4. Choose Apply.

Changing a filter value or grouping attribute

For an existing filter, you can change the filter value. You can also change the grouping attribute.

For example, you can change the Record state filter to look for ARCHIVED findings instead of ACTIVE findings.

To edit a filter or grouping attribute

1. On a filtered finding list, choose the filter or grouping attribute.

2. For Group by, choose the new attribute, then choose Apply.

3. For a filter, choose the new value, and then choose Apply.

Deleting a filter or grouping attribute

To delete a filter or grouping attribute, choose the x icon.

The list is updated automatically to reflect the change. When you remove the grouping attribute, the list changes from the list of field values back to a list of findings.

Available finding information

You can get a variety of findings details on the Security Hub console or by calling the GetFindings operation of the Security Hub API. Here is a partial list of the types of finding details you can get.

• Application metadata – Provides the name and Amazon Resource Name (ARN) of the application involved in a finding if you created an application. and added the AWS application tag to it. We recommend creating applications in AWS Service Catalog AppRegistry.

• Finding history – Provides the history of the finding in the last 90 days.

• Finding investigation in Detective (console only) – Provides a link to further investigate a finding in Detective using using automated log collection, security analytics, and AWS service resource exploration tools. This information is only included for Security Hub findings received from other AWS services if you enable Detective.

• Finding provider fields – displays the values from the finding provider for confidence, criticality, related findings, severity, and finding type.

• Parameters – Shows the current parameter values for a security control. Security Hub uses these parameter values when conducting security checks of the control.

• Remediation – Provides a link to the instructions for remediating failed control findings.

• Resource – Provides information about the AWS resource involved in a finding.

• Resource tags – Provides tag key and value information for the resources involved in a finding. You can tag resources that are supported by the GetResources operation of the AWS Resource Groups Tagging API. For more information about the inclusion of resource tags in findings, see Tags.

• Types and related findings – Contains information about the finding type.

• Vulnerability details – Information about a vulnerability that's detected in a finding and affected packages. These details are available if you enable Amazon Inspector for findings that Amazon Inspector sends to Security Hub.

Review the following sections to understand how to access these details for a finding.

Reviewing finding history

Finding history is a Security Hub feature that lets you track changes made to a finding during the last 90 days. It's available for active and archived findings. Finding history provides an immutable trail of changes made to a finding over time, including what the change was, when it occurred, and by which user.

In particular, you can track changes made to fields in the AWS Security Finding Format (ASFF). Security Hub tracks changes that you make manually and with automation rules.

Finding history is available in the Security Hub console, API, and AWS CLI.

If you're signed in to a Security Hub administrator account, you can get finding history for the administrator account and all member accounts.

Choose your preferred method, and follow the steps to get finding history.

Security Hub console

Reviewing finding history

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

2. In the left navigation pane, choose Findings.

3. Select a finding. In the panel that appears, choose the History tab.

Security Hub API

Reviewing finding history

1. Run GetFindings, or if you're using the AWS CLI, run the get-findings command. using appropriate filters as needed, to identify the finding that you want to view history for. The API response will give you the ProductArn and Id for the finding. You need the values for these fields in the third step.

2. Run GetFindingHistory, or if you're using the AWS CLI, run the get-finding-history command.

3. Identify the finding that you want to get history for with the ProductArn and Id fields. For more information about these fields, see AwsSecurityFindingIdentifier. You can only get history for one finding per request.

4. Provide values for StartTime. and EndTime to limit finding history to a specific period of time.

5. Provide a value for MaxResults to limit finding history to a specific number of results. If not provided, the API response returns the first 100 results of finding history.

6. Provide a value for NextToken to view the next 100 results (if applicable) for a finding. In your initial API request, the value of NextToken should be NULL.

The following CLI command retrieves history for the specified finding. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\) line-continuation character to improve readability.

$ aws securityhub get-finding-history \
--region us-west-2 \
--finding-identifier Id="a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",ProductArn="arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default" \
--max-results 2 \
--start-time "2021-09-30T15:53:35.573Z" \
--end-time "2021-09-31T15:53:35.573Z"

Reviewing finding details

Follow the steps to view finding details on the Security Hub console.

Security Hub console

Reviewing finding details

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

2. To display a finding list, take one of the following actions:

   • In the Security Hub navigation pane, choose Findings. Add search filters as necessary to narrow down the finding list.

   • In the Security Hub navigation pane, choose Insights. Choose an insight. Then on the results list, choose an insight result.

   • In the Security Hub navigation pane, choose Integrations. Choose See findings for an integration.

3. Select a finding title.

4. From the finding details panel, you can take additional actions as follows:

   • To display the complete JSON for the finding, choose the finding ID. From Finding JSON, download the finding JSON.

   • For findings that are based on AWS Config rules, to display a list of the applicable rules, choose Rules.

   • Choose Investigate with Macie to investigate sensitive data that's discovered in the finding in the Macie console. This option is only available if you enable Amazon Macie and its automated sensitive data discovery feature.

   • Choose Resources to view information about the resource involved in a finding.

   • Choose Investigate in Amazon Detective to investigate the finding in the Detective console. This option is only available if you enable Amazon Detective.

   • Choose the History tab to view up to 90 days of finding history.

Note

The top of the finding details panel contains overview information about the finding, including the account, severity, dates, and status. If you integrate with AWS Organizations and the account you're signed in to is an organization member account, then the details panel includes the account name. For member accounts that are invited manually rather than through the Organizations integration, the details panel only includes the account ID.

Security Hub API

Reviewing finding details

Use the GetFindings operation of the Security Hub API, or if you're using the AWS CLI, run the get-findings command.

You can provide one or more values for the Filters parameter to narrow the findings that you want to retrieve.

If the volume of results is too large, you can use the MaxResults parameter to limit the findings to a specified number and the NextToken parameter to paginate findings. Use the SortCriteria parameter to sort the findings by a specific field.

If you've enabled cross-Region aggregation and invoke this operation from the aggregation Region, the results include findings from the aggregation and linked Regions.

The following CLI command retrieves the findings that match the provided filters and sorts them in descending order of the LastObservedAt field. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\) line-continuation character to improve readability.

$ aws securityhub get-findings \
--filters '{"GeneratorId":[{"Value": "aws-foundational","Comparison":"PREFIX"}],"WorkflowStatus": [{"Value": "NEW","Comparison":"EQUALS"}],"Confidence": [{"Gte": 85}]}' --sort-criteria '{"Field": "LastObservedAt","SortOrder": "desc"}' --page-size 5 --max-items 100

PowerShell

Reviewing finding details

1. Use the Get-SHUBFinding cmdlet.

2. Optionally, populate the Filter parameter to narrow the findings that you want to retrieve.

Example

Get-SHUBFinding -Filter @{AwsAccountId = [Amazon.SecurityHub.Model.StringFilter]@{Comparison = "EQUALS"; Value = "XXX"};ComplianceStatus = [Amazon.SecurityHub.Model.StringFilter]@{Comparison = "EQUALS"; Value = 'FAILED'}}

Note

When you filter findings by CompanyName or ProductName, Security Hub uses the values that are part of the ProductFields ASFF object. Security Hub doesn't use the top-level CompanyName and ProductName fields.