AWS securityhub documentation change
Summary
Updated documentation to clarify how Security Hub CSPM generates, updates, and archives control findings. Added details about field updates in findings, historical behavior changes, and improved explanations of compliance tracking mechanisms.
Security assessment
The changes provide enhanced documentation about how Security Hub manages control findings, including updates to existing findings instead of creating new ones, tracking compliance status changes, and archiving logic. While this improves clarity for security posture management, there is no evidence of addressing a specific security vulnerability or incident.
Diff
diff --git a/securityhub/latest/userguide/controls-findings-create-update.md b/securityhub/latest/userguide/controls-findings-create-update.md index 83be44b81..e4fe5dd99 100644 --- a//securityhub/latest/userguide/controls-findings-create-update.md +++ b//securityhub/latest/userguide/controls-findings-create-update.md @@ -9 +9 @@ Consolidated control findingsGenerating, updating, and archiving control finding -AWS Security Hub Cloud Security Posture Management (CSPM) generates control findings when it runs checks against security controls. Control findings use the [AWS Security Finding Format (ASFF)](./securityhub-findings-format.html). +AWS Security Hub Cloud Security Posture Management (CSPM) generates and updates control findings when it runs checks against security controls. Control findings use the [AWS Security Finding Format (ASFF)](./securityhub-findings-format.html). @@ -34 +34 @@ If the size of a control finding exceeds the maximum of 240 KB, Security Hub CSP -If consolidated control findings is enabled for your account, Security Hub CSPM generates a single new finding or finding update for each security check of a control, even if a control applies to multiple enabled standards. For a list of controls and the standards that they apply to, see the [Control reference for Security Hub CSPM](./securityhub-controls-reference.html). We recommend enabling consolidated control findings to reduce finding noise. +If consolidated control findings is enabled for your account, Security Hub CSPM generates a single finding or finding update for each security check of a control, even if a control applies to multiple enabled standards. For a list of controls and the standards that they apply to, see the [Control reference for Security Hub CSPM](./securityhub-controls-reference.html). We recommend enabling consolidated control findings to reduce finding noise. @@ -40 +40 @@ If you use the [Security Hub CSPM integration with AWS Organizations](./security -If you disable consolidated control findings for your account, Security Hub CSPM generates a separate control finding for each security check and each enabled standard that includes a control. For example, if you enable four standards that share a control, you receive four separate findings after a security check for the control. If you enable consolidated control findings, you receive only one finding. +If you disable consolidated control findings for your account, Security Hub CSPM generates or updates a separate control finding for each enabled standard that includes a control. For example, if you enable four standards that share a control, you receive four separate findings after a security check for the control. If you enable consolidated control findings, you receive only one finding. @@ -48 +48 @@ To enable or disable consolidated control findings, you must be signed in to an -After you enable consolidated control findings, it can take up to 24 hours for Security Hub CSPM for generate new, consolidated findings and archive the original, standard-based findings. Similarly, after disabling consolidated control findings, it can take up to 24 hours for Security Hub CSPM to generate new, standard-based findings and archive the consolidated findings. During these times, you might see a mix of standard-agnostic and standard-based findings in your account. +After you enable consolidated control findings, it can take up to 24 hours for Security Hub CSPM to generate new consolidated findings and archive the existing standard-based findings. Similarly, after disabling consolidated control findings, it can take up to 24 hours for Security Hub CSPM to generate new standard-based findings and archive the existing consolidated findings. During these times, you might see a mix of standard-agnostic and standard-based findings in your account. @@ -87 +87,30 @@ The following AWS CLI command disables consolidated control findings. -Security Hub CSPM runs security checks on a [schedule](./securityhub-standards-schedule.html). A subsequent check against a given control can generate a new result. For example, the status of a control could change from `FAILED` to `PASSED`. In this case, Security Hub CSPM generates a new finding that contains the most recent result. If a subsequent check against a given control generates a result that is identical to the current result, Security Hub CSPM updates the existing finding. No new finding is generated. +Security Hub CSPM runs security checks on a [schedule](./securityhub-standards-schedule.html). The first time Security Hub CSPM runs a security check for a control, it generates a new finding for each AWS resource that the control checks. Each time Security Hub CSPM subsequently runs a security check for the control, it updates existing findings to report the results of the check. This means that you can use the data provided by individual findings to track compliance changes for particular resources against particular controls. + +For example, if the compliance status of a resource changes from `FAILED` to `PASSED` for a particular control, Security Hub CSPM doesn't generate a new finding. Instead, Security Hub CSPM updates the existing finding for the control and resource. In the finding, Security Hub CSPM changes the value for the compliance status (`Compliance.Status`) field to `PASSED`. Security Hub CSPM also updates the values for additional fields to reflect the results of the check—for example, the severity label, workflow status, and timestamps that indicate when Security Hub CSPM most recently ran the check and updated the finding. + +When reporting changes to compliance status, Security Hub CSPM might update any of the following fields in a control finding: + + * `Compliance.Status` – The new compliance status of the resource for the specified control. + + * `FindingProviderFields.Severity.Label` – The new qualitative representation of the severity of the finding, such as `LOW`, `MEDIUM`, or `HIGH`. + + * `FindingProviderFields.Severity.Original` – The new quantitative representation of the severity of the finding, such as `0` for a compliant resource. + + * `FirstObservedAt` – When the compliance status of the resource most recently changed. + + * `LastObservedAt` – When Security Hub CSPM most recently ran the security check for the specified control and resource. + + * `ProcessedAt` – When Security Hub CSPM most recently began processing the finding. + + * `ProductFields.PreviousComplianceStatus` – The previous compliance status (`Compliance.Status`) of the resource for the specified control. + + * `UpdatedAt` – When Security Hub CSPM most recently updated the finding. + + * `Workflow.Status` – The status of the investigation into the finding, based on the new compliance status of the resource for the specified control. + + + + +Whether Security Hub CSPM updates a field depends primarily on the results of the latest security check for the applicable control and resource. For example, if the compliance status of a resource changes from `PASSED` to `FAILED` for a particular control, Security Hub CSPM changes the workflow status of the finding to `NEW`. To track updates to individual findings, you can refer to the history of a finding. For details about individual fields in findings, see [AWS Security Finding Format (ASFF)](./securityhub-findings-format.html). + +In certain cases, Security Hub CSPM generates new findings for subsequent checks by a control, instead of updating existing findings. This can occur if there's an issue with the AWS Config rule that backs a control. If this happens, Security Hub CSPM archives the existing finding and generates a new finding for each check. In the new findings, the compliance status is `NOT_AVAILABLE` and the record state is `ARCHIVED`. After you address the issue with the AWS Config rule, Security Hub CSPM generates new findings and begins updating them to track subsequent changes to the compliance status of individual resources. @@ -103,0 +133,4 @@ To store archived control findings for more than 30 days, you can export the fin +###### Note + +Prior to July 3, 2025, Security Hub CSPM generated and updated control findings differently when the compliance status of a resource changed for a control. Previously, Security Hub CSPM created a new control finding and archived the existing finding for a resource. Therefore, you might have multiple archived findings for a particular control and resource until those findings expire (after 30 days). + @@ -106 +139 @@ To store archived control findings for more than 30 days, you can export the fin -You can use Security Hub CSPM automation rules to update or suppress specific control findings. If you suppress a finding, you can continue to access it in your account. However, suppression indicates your belief that no action is needed to address the finding. +You can use Security Hub CSPM automation rules to update or suppress specific control findings. If you suppress a finding, you can continue to access it. However, suppression indicates your belief that no action is needed to address the finding. @@ -110 +143 @@ By suppressing findings, you can reduce finding noise. For example, you might su -Automation rules are appropriate when you want to update or suppress specific control findings. However, if a control isn't relevant to your organization or use case, we recommend [disabling the control](./disable-controls-overview.html). When you disable a control, Security Hub CSPM doesn't run security checks on it, and you aren't charged for it. +Automation rules are appropriate when you want to update or suppress specific control findings. However, if a control isn't relevant to your organization or use case, we recommend [disabling the control](./disable-controls-overview.html). If you disable a control, Security Hub CSPM doesn't run security checks for it and you aren't charged for it. @@ -122 +155 @@ In findings generated by security checks for controls, the [Compliance](./asff-t - * `Status` – The result of the most recent check that Security Hub CSPM ran for the control. The results of the previous checks are kept in an archived state. + * `Status` – The result of the most recent check that Security Hub CSPM ran for the control. The results of previous checks are retained in the history of the finding. @@ -174 +207 @@ Reason code | Compliance status | Description -When Security Hub CSPM runs security checks and generates control findings, the [ProductFields](./asff-top-level-attributes.html#asff-productfields) attribute in ASFF includes the following fields: +In findings generated by security checks for controls, the [ProductFields](./asff-top-level-attributes.html#asff-productfields) attribute in the AWS Security Finding Format (ASFF) can include the following fields. @@ -179 +212 @@ When Security Hub CSPM runs security checks and generates control findings, the -Describes why Security Hub CSPM has archived existing findings. +Describes why Security Hub CSPM archived a finding. @@ -181 +214 @@ Describes why Security Hub CSPM has archived existing findings. -For example, Security Hub CSPM archives existing findings when you disable a control or standard and when you turn consolidated control findings on or off. +For example, Security Hub CSPM archives existing findings when you disable a control or standard, or you enable or disable consolidated control findings. @@ -186 +219,6 @@ For example, Security Hub CSPM archives existing findings when you disable a con -Provides the reason why Security Hub CSPM has archived existing findings. +Specifies why Security Hub CSPM archived a finding. + +For example, Security Hub CSPM archives existing findings when you disable a control or standard, or you enable or disable consolidated control findings. + +`PreviousComplianceStatus` + @@ -188 +226 @@ Provides the reason why Security Hub CSPM has archived existing findings. -For example, Security Hub CSPM archives existing findings when you disable a control or standard and when you turn consolidated control findings on or off. +The previous compliance status (`Compliance.Status`) of the resource for the specified control, as of the most recent update to the finding. If the compliance status of the resource didn't change during the most recent update, this value is the same as the value for the `Compliance.Status` field of the finding. For a list of possible values, see [Evaluating compliance status and control status](./controls-overall-status.html). @@ -195,3 +233 @@ The ARN of the standard associated with the control. -For the CIS AWS Foundations Benchmark standard, the field is `StandardsGuideArn`. - -For PCI DSS and AWS Foundational Security Best Practices standards, the field is `StandardsArn`. +For the CIS AWS Foundations Benchmark standard, the field is `StandardsGuideArn`. For the PCI DSS and AWS Foundational Security Best Practices standards, the field is `StandardsArn`. @@ -206,3 +242 @@ The ARN of the account's subscription to the standard. -For the CIS AWS Foundations Benchmark standard, the field is `StandardsGuideSubscriptionArn`. - -For the PCI DSS and AWS Foundational Security Best Practices standards, the field is `StandardsSubscriptionArn`. +For the CIS AWS Foundations Benchmark standard, the field is `StandardsGuideSubscriptionArn`. For the PCI DSS and AWS Foundational Security Best Practices standards, the field is `StandardsSubscriptionArn`. @@ -215 +249 @@ These fields are removed if you enable consolidated control findings. -The identifier of the control. +The identifier for the control. @@ -217,3 +251 @@ The identifier of the control. -For the CIS AWS Foundations Benchmark standard, the field is `RuleId`. - -For other standards, the field is `ControlId`. +For the CIS AWS Foundations Benchmark standard, the field is `RuleId`. For other standards, the field is `ControlId`. @@ -226 +258 @@ These fields are removed in favor of `Compliance.SecurityControlId` if you enabl -The URL to the remediation information for the control. This field is removed in favor of `Remediation.Recommendation.Url` if you enable consolidated control findings. +The URL for remediation information for the control. This field is removed in favor of `Remediation.Recommendation.Url` if you enable consolidated control findings. @@ -246 +278 @@ The ARN of the control. This field is removed if you enable consolidated control -For control-based findings, the product name is Security Hub CSPM. +For control findings, the product name is `Security Hub`. @@ -251 +283 @@ For control-based findings, the product name is Security Hub CSPM. -For control-based findings, the company name is AWS. +For control findings, the company name is `AWS`. @@ -261 +293,3 @@ A description of the issue uncovered by the control. -The identifier of the finding. This field doesn't reference a standard if you enable consolidated control findings. +The identifier for the finding. + +This field doesn't reference a standard if you enable consolidated control findings. @@ -265 +299 @@ The identifier of the finding. This field doesn't reference a standard if you en -The severity assigned to a Security Hub CSPM control identifies the importance of the control. The severity of a control determines the severity label assigned to the control findings. +The severity assigned to a Security Hub CSPM control indicates the importance of the control. The severity of a control determines the severity label assigned to the control findings. @@ -271,7 +305 @@ The severity of a control is determined based on an assessment of the following - * **How difficult is it for a threat actor to take advantage of the configuration weakness associated with the control?** - -The difficulty is determined by the amount of sophistication or complexity that is required to use the weakness to carry out a threat scenario. - - * **How likely is it that the weakness will lead to a compromise of your AWS accounts or resources?** - -A compromise of your AWS accounts or resources means that confidentiality, integrity, or availability of your data or AWS infrastructure is damaged in some way. + * **How difficult is it for a threat actor to take advantage of the configuration weakness associated with the control?** The difficulty is determined by the amount of sophistication or complexity that is required to use the weakness to carry out a threat scenario. @@ -279 +307 @@ A compromise of your AWS accounts or resources means that confidentiality, integ -The likelihood of compromise indicates how likely it is that the threat scenario will result in a disruption or breach of your AWS services or resources. + * **How likely is it that the weakness will lead to a compromise of your AWS accounts or resources?** A compromise of your AWS accounts or resources means that confidentiality, integrity, or availability of your data or AWS infrastructure is damaged in some way. The likelihood of compromise indicates how likely it is that the threat scenario will result in a disruption or breach of your AWS services or resources. @@ -297 +325 @@ However, the likelihood of a compromise is much higher if the threat actor acqui -The severity does not take into account the criticality of the underlying resource. Criticality is the level of importance of the resources that are associated with the finding. For example, a resource that is associated with a mission critical application is more critical than one that is associated with nonproduction testing. To capture resource criticality information, use the `Criticality` field of the AWS Security Finding Format (ASFF). +The severity does not take into account the criticality of the underlying resource. Criticality is the level of importance of the resources that are associated with the finding. For example, a resource that is associated with a mission critical application is more critical than one that is associated with non-production testing. To capture resource criticality information, use the `Criticality` field of the AWS Security Finding Format (ASFF).