AWS securityhub documentation change
Summary
Updated documentation for viewing Security Hub findings with improved clarity and terminology. Changes include: formatting adjustments (e.g., italicizing 'finding'), clarifying history retention periods (90 days for active vs 30 days for archived findings), improved console navigation instructions, and updated API/CLI examples.
Security assessment
The changes are primarily editorial improvements and clarifications of existing functionality. No specific security vulnerabilities or new security features are introduced. Updates about history retention periods and automation rules describe existing capabilities rather than addressing security flaws.
Diff
diff --git a/securityhub/latest/userguide/securityhub-findings-viewing.md b/securityhub/latest/userguide/securityhub-findings-viewing.md index 6a00c73a5..b3624a254 100644 --- a//securityhub/latest/userguide/securityhub-findings-viewing.md +++ b//securityhub/latest/userguide/securityhub-findings-viewing.md @@ -5 +5 @@ -Instructions for reviewing finding details and history +Reviewing finding details and history @@ -9 +9 @@ Instructions for reviewing finding details and history -In AWS Security Hub Cloud Security Posture Management (CSPM), a finding is an observable record of a security check or security-related detection. Security Hub CSPM generates a finding when it completes a security check of a control and when it ingests a finding from an integrated AWS service or third-party product. Each finding includes a history of changes and other details, such as a severity rating and information about the affected resources. +In AWS Security Hub Cloud Security Posture Management (CSPM), a _finding_ is an observable record of a security check or security-related detection. Security Hub CSPM generates a finding when it completes a security check of a control and when it ingests a finding from an integrated AWS service or third-party product. Each finding includes a history of changes and other details, such as a severity rating and information about the affected resources. @@ -11 +11 @@ In AWS Security Hub Cloud Security Posture Management (CSPM), a finding is an ob -You can review finding history and other finding details on the Security Hub CSPM console and programmatically through the Security Hub CSPM API and AWS CLI. +You can review the history and other details of individual findings on the Security Hub CSPM console or programmatically with the Security Hub CSPM API or the AWS CLI. @@ -13 +13 @@ You can review finding history and other finding details on the Security Hub CSP -To help you streamline your analysis, the Security Hub CSPM console opens a finding panel when you select a specific finding. The panel includes different menus and tabs for viewing different finding details. +To help you streamline your analysis, the Security Hub CSPM console displays a finding panel when you choose a specific finding. The panel includes different menus and tabs for reviewing specific details of a finding. @@ -18 +18 @@ To help you streamline your analysis, the Security Hub CSPM console opens a find -From this menu, you can review the complete JSON of a finding or add notes. A finding can have no more than one note attached to it at a time. This menu also provides options to [set the workflow status of a finding](./findings-workflow-status.html) or [send a finding to a custom action](./findings-custom-action.html) in Amazon EventBridge. +From this menu, you can review the complete JSON of a finding or add notes. A finding can have only one note attached to it at a time. This menu also provides options to [set the workflow status of a finding](./findings-workflow-status.html) or [send a finding to a custom action](./findings-custom-action.html) in Amazon EventBridge. @@ -28 +28 @@ From this menu, you can investigate a finding in Amazon Detective. Detective ext -This tab provides a summary of the finding. For example, you can see when the finding was created and last updated, in which account it exists, and the source of the finding. For control findings, you can also see the name of the associated AWS Config rule and a link to remediation instructions in the Security Hub CSPM documentation. +This tab provides a summary of a finding. For example, you can determine when a finding was created and last updated, in which account it exists, and the source of the finding. For control findings, this tab also shows the name of the associated AWS Config rule and a link to remediation guidance in the Security Hub CSPM documentation. @@ -30 +30 @@ This tab provides a summary of the finding. For example, you can see when the fi -On the **Resources** snapshot within the **Overview** tab, you can get a brief overview of the resources involved in a finding. For some resources, we include an option to **Open resource** and directly view an impacted resource in the relevant AWS service console. The **History** snapshot shows up to two changes made to the finding on the most recent date for which history is being tracked. The date must fall within the last 90 days. As an example, if you made one change yesterday and one today, the snapshot shows only today's change. To view earlier entries, switch to the **History** tab. +In the **Resources** snapshot on the **Overview** tab, you can get a brief overview of the resources involved in a finding. For some resources, this includes an **Open resource** option, which links directly to an impacted resource on the relevant AWS service console. The **History** snapshot shows up to two changes made to the finding on the most recent date for which history is being tracked. For example, if you made one change yesterday and another one today, the snapshot shows today's change. To review earlier entries, switch to the **History** tab. @@ -32 +32 @@ On the **Resources** snapshot within the **Overview** tab, you can get a brief o -The **Compliance** row expands to show more details. For example, for controls that include parameters, you can see the current parameter values that Security Hub CSPM uses when conducting security checks. +The **Compliance** row expands to show more details. For example, if a control includes parameters, you can review the parameter values that Security Hub CSPM currently uses when conducting security checks for the control. @@ -37 +37 @@ The **Compliance** row expands to show more details. For example, for controls t -This tab provides details about the resources involved in a finding. If you're signed in to the account that owns a resource, you can view the resource in the relevant AWS service console. If you're not the owner of a resource, the console displays the AWS account ID of the owner. +This tab provides details about the resources involved in a finding. If you're signed in to the account that owns a resource, you can review the resource in the applicable AWS service console. If you're not the owner of a resource, this tab displays the AWS account ID for the owner. @@ -39 +39 @@ This tab provides details about the resources involved in a finding. If you're s -The **Details** row shows resource-specific details about the finding by displaying the [ResourceDetails](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_ResourceDetails.html) section of the finding JSON. +The **Details** row shows resource-specific details in a finding. It shows the [ResourceDetails](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_ResourceDetails.html) section of the finding in JSON format. @@ -41 +41 @@ The **Details** row shows resource-specific details about the finding by display -The **Tags** row shows tag key and value information for the resources involved in a finding. Resources that are [supported by the GetResources operation](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html) of the AWS Resource Groups Tagging API can be tagged. Security Hub CSPM calls this operation through the [service-linked role](./using-service-linked-roles.html) when processing new or updated findings and retrieves the resource tags if the AWS Security Finding Format (ASFF) `Resource.Id` field is populated with the AWS resource ARN. Security Hub CSPM ignores invalid resource IDs. For more information about the inclusion of resource tags in findings, see [Tags](./asff-resources-attributes.html#asff-resources-tags). +The **Tags** row shows tag keys and values that are assigned to the resources involved in a finding. Resources that are [supported by the GetResources operation](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html) of the AWS Resource Groups Tagging API can be tagged. Security Hub CSPM calls this operation by using a [service-linked role](./using-service-linked-roles.html) when processing new or updated findings, and retrieves the resource tags if the AWS Security Finding Format (ASFF) `Resource.Id` field is populated with the ARN of a resource. Security Hub CSPM ignores invalid resource IDs. For more information about the inclusion of resource tags in findings, see [Tags](./asff-resources-attributes.html#asff-resources-tags). @@ -43 +43 @@ The **Tags** row shows tag key and value information for the resources involved -**Finding history tab** +**History tab** @@ -46 +46 @@ The **Tags** row shows tag key and value information for the resources involved -This tab tracks the history of a finding for the past 90 days. Finding history is available for active and archived findings. It provides an immutable trail of changes made to a finding over time, including what AWS Security Finding Format (ASFF) field changed, when the change occurred, and by which user. Each page on the tab displays up to 20 changes. More recent changes are displayed first. If you're signed in to a Security Hub CSPM administrator account, the finding history shown is for the administrator account and all member accounts. +This tab tracks the history of a finding. Finding history is available for active and archived findings. It provides an immutable trail of changes made to a finding over time, including what ASFF field changed, when the change occurred, and by which user. Each page on the tab displays up to 20 changes. More recent changes are displayed first. @@ -48 +48,3 @@ This tab tracks the history of a finding for the past 90 days. Finding history i -Finding history includes changes that a user made manually or automatically through [Security Hub CSPM automation rules](./automation-rules.html). Finding history doesn't include changes to top-level timestamp fields, such as the `CreatedAt` and `UpdatedAt` fields. +For active findings, finding history is available for up to 90 days. For archived findings, finding history is available for up to 30 days. Finding history includes changes that were made manually, or automatically by [Security Hub CSPM automation rules](./automation-rules.html). It doesn't include changes to top-level timestamp fields, such as the `CreatedAt` and `UpdatedAt` fields. + +If you're signed in to a Security Hub CSPM administrator account, finding history is for the administrator account and all member accounts. @@ -53 +55 @@ Finding history includes changes that a user made manually or automatically thro -This tab includes data from the [Action](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Action.html), [Malware](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Malware.html), and [ProcessDetails](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Process.html) objects of the ASFF, including the type of threat and whether a resource is the target or actor. This object typically applies to findings that originate in Amazon GuardDuty. +This tab includes data from the [Action](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Action.html), [Malware](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Malware.html), and [ProcessDetails](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Process.html) objects of the ASFF, including the type of threat and whether a resource is the target or actor. These details typically apply to findings that originate in Amazon GuardDuty. @@ -58,3 +60 @@ This tab includes data from the [Action](https://docs.aws.amazon.com/securityhub -This tab displays data from the [Vulnerability](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Vulnerability.html) object of the ASFF, including whether there are exploits or available fixes associated with a finding. This object typically applies to findings that originate in Amazon Inspector. - -The rows in each tab include a copy or filter option. For example, if you're on the panel for a finding that has a workflow status of **Notified** , you can choose the filter option next to the **Workflow status** row. If you choose **Show all findings with this value** filters the finding list so that it displays only findings with the same workflow status. +This tab displays data from the [Vulnerability](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Vulnerability.html) object of the ASFF, including whether there are exploits or available fixes associated with a finding. These details typically apply to findings that originate in Amazon Inspector. @@ -62 +62 @@ The rows in each tab include a copy or filter option. For example, if you're on -Review the following section to understand how to access these details for a finding. +The rows on each tab include a copy or filter option. For example, if you open the panel for a finding that has a workflow status of **Notified** , you can choose the filter option next to the **Workflow status** row. If you choose **Show all findings with this value** , Security Hub CSPM filters the findings table and displays only findings with the same workflow status. @@ -64 +64 @@ Review the following section to understand how to access these details for a fin -## Instructions for reviewing finding details and history +## Reviewing finding details and history @@ -66 +66 @@ Review the following section to understand how to access these details for a fin -Choose your preferred method, and follow the steps to view finding details in Security Hub CSPM. +Choose your preferred method, and follow the steps to review finding details in Security Hub CSPM. @@ -73 +73 @@ Security Hub CSPM console -###### Reviewing finding details and history (console) +###### Reviewing finding details and history @@ -77 +77 @@ Security Hub CSPM console - 2. To display a finding list, take one of the following actions: + 2. To display a finding list, do one of the following: @@ -79 +79 @@ Security Hub CSPM console - * In the Security Hub CSPM navigation pane, choose **Findings**. Add search filters as necessary to narrow down the finding list. + * In the navigation pane, choose **Findings**. Add search filters as necessary to narrow the finding list. @@ -81 +81 @@ Security Hub CSPM console - * In the Security Hub CSPM navigation pane, choose **Insights**. Choose an insight. Then on the results list, choose an insight result. + * In the navigation pane, choose **Insights**. Choose an insight. Then, in the results list, choose an insight result. @@ -83 +83 @@ Security Hub CSPM console - * In the Security Hub CSPM navigation pane, choose **Integrations**. Choose **See findings** for an integration. + * In the navigation pane, choose **Integrations**. Choose **See findings** for an integration. @@ -85 +85 @@ Security Hub CSPM console - * In the Security Hub CSPM navigation pane, choose **Controls**. + * In the navigation pane, choose **Controls**. @@ -87 +87 @@ Security Hub CSPM console - 3. Select a finding title. + 3. Choose a finding. The finding panel displays the details of the finding. @@ -89 +89 @@ Security Hub CSPM console - 4. On the finding panel, do one of the following: + 4. In the finding panel, do any of the following: @@ -91 +91 @@ Security Hub CSPM console - * Choose the **Actions** menu to take action on the finding. + * To review specific details for the finding, choose a tab. @@ -93 +93 @@ Security Hub CSPM console - * Choose the **Investigate** menu to investigate the finding in Amazon Detective. + * To take action on the finding, choose an option from the **Actions** menu. @@ -95 +95 @@ Security Hub CSPM console - * Select a tab to view more details about the finding. + * To investigate the finding in Amazon Detective, choose an **Investigate** option. @@ -102 +102 @@ Security Hub CSPM console -If you integrate with AWS Organizations and the account you're signed in to is an organization member account, the finding panel includes the account name. For member accounts that are invited manually rather than through Organizations, the finding panel only includes the account ID. +If you integrate with AWS Organizations and you're signed in to a member account, the finding panel includes the account name. For member accounts that are invited manually, instead of through Organizations, the finding panel includes only the account ID. @@ -107,5 +107 @@ Security Hub CSPM API -**Reviewing finding details and history (API)** - -Use the [GetFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindings.html) operation of the Security Hub CSPM API, or if you're using the AWS CLI, run the [get-findings](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-findings.html) command. - -You can provide one or more values for the `Filters` parameter to narrow the findings that you want to retrieve. +Use the [GetFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindings.html) operation of the Security Hub CSPM API, or if you're using the AWS CLI, run the [get-findings](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-findings.html) command. You can provide one or more values for the `Filters` parameter to narrow the findings to retrieve. @@ -115,3 +111 @@ If the volume of results is too large, you can use the `MaxResults` parameter to -If you've enabled [cross-Region aggregation](./finding-aggregation.html) 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. +For example, the following AWS CLI command retrieves the findings that match the specified filter criteria, and sorts the results in descending order by the `LastObservedAt` field. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\\) line-continuation character to improve readability. @@ -124,3 +118 @@ The following CLI command retrieves the findings that match the provided filters -To review finding history, use the [GetFindingHistory](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindingHistory.html) operation. If you're using the AWS CLI, run the [get-finding-history](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-finding-history.html) command. - -Identify the finding that you want to get history for with the `ProductArn` and `Id` fields. For more information about these fields, see [AwsSecurityFindingIdentifier](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_AwsSecurityFindingIdentifier.html). You can only get history for one finding per request. +To review finding history, use the [GetFindingHistory](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindingHistory.html) operation. If you're using the AWS CLI, run the [get-finding-history](https://docs.aws.amazon.com/cli/latest/reference/securityhub/get-finding-history.html) command. Identify the finding that you want to get history for with the `ProductArn` and `Id` fields. For information about these fields, see [AwsSecurityFindingIdentifier](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_AwsSecurityFindingIdentifier.html). Each request can retrieve the history for only one finding. @@ -128 +120 @@ Identify the finding that you want to get history for with the `ProductArn` and -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. +For example, the following AWS CLI command retrieves the 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. @@ -141,5 +133 @@ PowerShell -**Reviewing finding details (PowerShell)** - -Use the `Get-SHUBFinding` cmdlet. - -Optionally, populate the `Filter` parameter to narrow the findings that you want to retrieve. +Use the `Get-SHUBFinding` cmdlet. Optionally populate the `Filter` parameter to narrow the findings to retrieve. @@ -147 +135 @@ Optionally, populate the `Filter` parameter to narrow the findings that you want -The following cmdlet retrieves the findings that match the provided filters +For example, the following cmdlet retrieves the findings that match the specified filters. @@ -154 +142 @@ The following cmdlet retrieves the findings that match the provided filters -When you filter findings by `CompanyName` or `ProductName`, Security Hub CSPM uses the values that are part of the `ProductFields` ASFF object. Security Hub CSPM doesn't use the top-level `CompanyName` and `ProductName` fields. +If you filter findings by `CompanyName` or `ProductName`, Security Hub CSPM uses the values that are part of the `ProductFields` ASFF object. Security Hub CSPM doesn't use the top-level `CompanyName` and `ProductName` fields.