Viewing finding details

From a finding list on the Security Hub console, you can display a details panel for a finding. The details panel includes the history of the finding during the last 90 days. You can also get finding details and finding history programmatically.

Available finding details

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.

• 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.

• Types and related findings – Contains information about the 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.

• 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.

• 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.

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

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

• 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.

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

Retrieving finding details (console)

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

Retrieving finding details (console)

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. Select a finding title to view the details panel for the finding.

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.

To display the complete JSON for the finding, choose the finding ID. From Finding JSON, you can download the finding JSON to a file.

To add a field value to the finding list filter, choose the search icon next to the field.

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

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

Retrieving finding details (programmatic)

Choose your preferred method, and follow the steps to programmatically get a list of Security Hub findings. You can specify filters to narrow down the list of findings to a specific subset.

The following tabs include instructions in a few languages for retrieving findings. For support in additional languages, see Tools to Build on AWS.

Note

When you filter by CompanyName or ProductName, Security Hub uses the values that are in ProductFields. It doesn't use the top-level CompanyName and ProductName fields.

Security Hub API

1. Run GetFindings.

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

3. Optionally, populate the MaxResults parameter to limit the findings to a specified number and the NextToken parameter to paginate findings.

4. Optionally, populate the SortCriteria parameter to sort the findings by a specific field.

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

AWS CLI

1. At the command line, run the get-findings command.

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

3. Optionally, populate the max-items parameter to limit the findings to a specified number and the page-size parameter to paginate findings.

4. Optionally, populate the sort-criteria parameter to sort the findings by a specific field.

get-findings --filters <filter criteria JSON> --sort-criteria <sort criteria> --page-size <findings per page> --max-items <maximum number of results>

Example

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

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

PowerShell

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'}}

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

Viewing finding history (console)

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

1. Run GetFindings, 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.

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.

Example API request:

{
"FindingIdentifier": {
  "ProductArn": "arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default",
  "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
},
"MaxResults": 2,
"StartTime": "2021-09-30T15:53:35.573Z",
"EndTime": "2021-09-31T15:53:35.573Z"
}

AWS CLI

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

2. 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 start-time and end-time to limit finding history to a specific period of time.

5. Provide a value for max-results to limit finding history to a specific number of results. If not provided, the command returns the first 100 results of finding history.

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

   Example command:

   aws securityhub --region us-west-2 \
   get-finding-history
   --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"