AWS securityhub documentation change
Summary
Updated documentation to clarify automation rule behavior, including fields auto-populated by Security Hub CSPM and interactions between BatchImportFindings/BatchUpdateFindings operations.
Security assessment
The changes clarify operational behavior of automation rules and field population logic, but do not address vulnerabilities or introduce new security features. Updates focus on documentation accuracy and user understanding of existing mechanisms.
Diff
diff --git a/securityhub/latest/userguide/automation-rules.md b/securityhub/latest/userguide/automation-rules.md index ce0071834..605116712 100644 --- a//securityhub/latest/userguide/automation-rules.md +++ b//securityhub/latest/userguide/automation-rules.md @@ -116 +116 @@ If you want Security Hub CSPM to stop generating findings for a specific control -An automation rule evaluates new and updated findings that Security Hub CSPM generates or ingests through the [BatchImportFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchImportFindings.html) operation _after_ you create the rule. Security Hub CSPM updates control findings every 12-24 hours or when the associated resource changes state. For more information, see [Schedule for running security checks](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-schedule.html). +An automation rule evaluates new and updated findings that Security Hub CSPM generates or ingests through the [BatchImportFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchImportFindings.html) operation _after_ you create the rule. Security Hub CSPM updates control findings every 12-24 hours or when the associated resource changes state. For more information, see [Schedule for running security checks](./securityhub-standards-schedule.html). @@ -118 +118 @@ An automation rule evaluates new and updated findings that Security Hub CSPM gen -Automation rules evaluate original, provider-supplied findings. Providers can supply new findings and update existing findings through the `BatchImportFindings` operation of the Security Hub CSPM API. Rules aren't triggered when you update finding fields after rule creation through the [BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html) operation. If you create an automation rule and make a `BatchUpdateFindings` update that both affect the same finding field, the last update sets the value for that field. Take the following example: +Automation rules evaluate original, provider-supplied findings. Providers can supply new findings and update existing findings by using the `BatchImportFindings` operation of the Security Hub CSPM API. If the following fields don't exist in the original finding, Security Hub CSPM automatically populates the fields and then uses the populated values in the evaluation by the automation rule: @@ -120 +120,16 @@ Automation rules evaluate original, provider-supplied findings. Providers can su - 1. You use `BatchUpdateFindings` to update the `Workflow.Status` field of a finding from `NEW` to `NOTIFIED`. + * `AwsAccountName` + + * `CompanyName` + + * `ProductName` + + * `Resource.Tags` + + * `Workflow.Status` + + + + +After you create one or more automation rules, the rules aren't triggered if you update finding fields by using the [BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html) operation. If you create an automation rule and make a `BatchUpdateFindings` update that both affect the same finding field, the last update sets the value for that field. Take the following example: + + 1. You use the `BatchUpdateFindings` operation to change the value for the `Workflow.Status` field of a finding from `NEW` to `NOTIFIED`. @@ -124 +139 @@ Automation rules evaluate original, provider-supplied findings. Providers can su - 3. You create an automation rule that changes the `Workflow.Status` field of the finding from `NEW` to `SUPPRESSED` (recall that rules ignore updates made with `BatchUpdateFindings`). + 3. You create an automation rule that changes the `Workflow.Status` field of the finding from `NEW` to `SUPPRESSED`. (Recall that rules ignore updates made using the `BatchUpdateFindings` operation.) @@ -126 +141 @@ Automation rules evaluate original, provider-supplied findings. Providers can su - 4. The finding provider uses `BatchImportFindings` to update the finding and changes the `Workflow.Status` field to `NEW`. + 4. The finding provider uses the `BatchImportFindings` operation to update the finding and changes the value for the `Workflow.Status` field of the finding to `NEW`. @@ -128 +143 @@ Automation rules evaluate original, provider-supplied findings. Providers can su - 5. If you call `GetFindings`, the `Workflow.Status` field now has a value of `SUPPRESSED` because the automation rule was applied, and the rule was the last action taken on the finding. + 5. If you call `GetFindings`, the `Workflow.Status` field now has a value of `SUPPRESSED`. This is the case because the automation rule was applied, and the rule was the last action taken on the finding. @@ -133 +148 @@ Automation rules evaluate original, provider-supplied findings. Providers can su -When you create or edit a rule on the Security Hub CSPM console, the console displays a beta of findings that match the rule criteria. Whereas automation rules evaluate original findings sent by the finding provider, the console beta reflects findings in their final state as they would be shown in a response to the [GetFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindings.html) API operation (that is, after rule actions or other updates are applied to the finding). +When you create or edit a rule on the Security Hub CSPM console, the console displays a beta of findings that match the rule criteria. Whereas automation rules evaluate original findings sent by the finding provider, the console beta reflects findings in their final state as they would be shown in a response to the [GetFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindings.html) operation (that is, after rule actions or other updates are applied to the finding).