Understanding automation rules in Security Hub

You can use automation rules to automatically update findings in AWS Security Hub. As it ingests findings, Security Hub can apply a variety of rule actions, such as suppressing findings, changing their severity, and adding notes. Such rule actions modify findings that match your specified criteria.

Examples of use cases for automation rules include the following:

• Elevating a finding’s severity to CRITICAL if the finding's resource ID refers to a business-critical resource.

• Elevating a finding’s severity from HIGH to CRITICAL if the finding affects resources in specific production accounts.

• Assigning specific findings that have a severity of INFORMATIONAL a SUPPRESSED workflow status.

You can create and manage automation rules from a Security Hub administrator account only.

Rules apply to both new findings and updated findings. You can create a custom rule from scratch, or use a rule template provided by Security Hub. You can also start with a template and modify it as needed.

Defining rule criteria and rule actions

From a Security Hub administrator account, you can create an automation rule by defining one or more rule criteria and one or more rule actions. When a finding matches the defined criteria, Security Hub applies the rule actions to it. For more information about available criteria and actions, see Available rule criteria and rule actions.

Security Hub currently supports a maximum of 100 automation rules for each administrator account.

The Security Hub administrator account can also edit, view, and delete automation rules. A rule applies to matching findings in the administrator account and all of its member accounts. By providing member account IDs as rule criteria, Security Hub administrators can also use automation rules to update or suppress findings in specific member accounts.

An automation rule applies only in the AWS Region in which it's created. To apply a rule in multiple Regions, the administrator must create the rule in each Region. This can be done through the Security Hub console, Security Hub API, or AWS CloudFormation. You can also use a multi-Region deployment script.

Important

Automation rules apply to new and updated findings that Security Hub generates or ingests after you create the rule. Security Hub updates control findings every 12-24 hours or when the associated resource changes state. For more information, see Schedule for running security checks. Automation rules evaluate original, provider-supplied finding fields. Rules aren't triggered when you update finding fields after rule creation through BatchUpdateFindings.

Specifying rule order

When creating automation rules, you assign each rule an order. This determines the order in which Security Hub applies your automation rules, and becomes important when multiple rules relate to the same finding or finding field.

When multiple rule actions relate to the same finding or finding field, the rule with the highest numerical value for rule order applies last and has the ultimate effect.

When you create a rule in the Security Hub console, Security Hub automatically assigns rule order based on the order of rule creation. The most recently created rule has the lowest numerical value for rule order and therefore applies first. Security Hub applies subsequent rules in ascending order.

When you create a rule through the Security Hub API or AWS CLI, Security Hub applies the rule with the lowest numerical value for RuleOrder first. It then applies subsequent rules in ascending order. If multiple findings have the same RuleOrder, Security Hub applies a rule with an earlier value for the UpdatedAt field first (that is, the rule which was most recently edited applies last).

You can modify rule order at any time.

Example of rule order:

Rule A (rule order is 1):

• Rule A criteria

  • ProductName = Security Hub

  • Resources.Type is S3 Bucket

  • Compliance.Status = FAILED

  • RecordState is NEW

  • Workflow.Status = ACTIVE

• Rule A actions

  • Update Confidence to 95

  • Update Severity to CRITICAL

Rule B (rule order is 2):

• Rule B criteria

  • AwsAccountId = 123456789012

• Rule B actions

  • Update Severity to INFORMATIONAL

Rule A actions apply first to Security Hub findings that match Rule A criteria. Next, Rule B actions apply to Security Hub findings with the specified account ID. In this example, since Rule B applies last, the end value of Severity in findings from the specified account ID is INFORMATIONAL. Based on the Rule A action, the end value of Confidence in matched findings is 95.

Available rule criteria and rule actions

The following AWS Security Finding Format (ASFF) fields are currently supported as criteria for automation rules:

ASFF field	Filters	Field type
AwsAccountId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
AwsAccountName	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
CompanyName	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ComplianceAssociatedStandardsId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ComplianceSecurityControlId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ComplianceStatus	Is, Is Not	Select: [FAILED, NOT_AVAILABLE, PASSED, WARNING]
Confidence	Eq (equal-to), Gte (greater-than-equal), Lte (less-than-equal)	Number
CreatedAt	Start, End, DateRange	Date (formatted as 2022-12-01T21:47:39.269Z)
Criticality	Eq (equal-to), Gte (greater-than-equal), Lte (less-than-equal)	Number
Description	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
FirstObservedAt	Start, End, DateRange	Date (formatted as 2022-12-01T21:47:39.269Z)
GeneratorId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
Id	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
LastObservedAt	Start, End, DateRange	Date (formatted as 2022-12-01T21:47:39.269Z)
NoteText	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
NoteUpdatedAt	Start, End, DateRange	Date (formatted as 2022-12-01T21:47:39.269Z)
NoteUpdatedBy	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ProductArn	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ProductName	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
RecordState	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
RelatedFindingsId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
RelatedFindingsProductArn	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourceApplicationArn	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourceApplicationName	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourceDetailsOther	CONTAINS, EQUALS, NOT_CONTAINS, NOT_EQUALS	Map
ResourceId	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourcePartition	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourceRegion	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
ResourceTags	CONTAINS, EQUALS, NOT_CONTAINS, NOT_EQUALS	Map
ResourceType	Is, Is Not	Select (see Resources supported by ASFF)
SeverityLabel	Is, Is Not	Select: [CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL]
SourceUrl	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
Title	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
Type	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
UpdatedAt	Start, End, DateRange	Date (formatted as 2022-12-01T21:47:39.269Z)
UserDefinedFields	CONTAINS, EQUALS, NOT_CONTAINS, NOT_EQUALS	Map
VerificationState	CONTAINS, EQUALS, PREFIX, NOT_CONTAINS, NOT_EQUALS, PREFIX_NOT_EQUALS	String
WorkflowStatus	Is, Is Not	Select: [NEW, NOTIFIED, RESOLVED, SUPPRESSED]

For criteria that are labeled as string fields, using different filter operators on the same field affects the evaluation logic. For more information, see StringFilter in the AWS Security Hub API Reference.

Each criterion supports a maximum number of values that can be used to filter matching findings. For the limits on each criterion, see AutomationRulesFindingFilters in the AWS Security Hub API Reference.

The following ASFF fields are currently supported as actions for automation rules:

• Confidence

• Criticality

• Note

• RelatedFindings

• Severity

• Types

• UserDefinedFields

• VerificationState

• Workflow

For more information about specific ASFF fields, see AWS Security Finding Format (ASFF) syntax and ASFF examples.

Tip

If you want Security Hub to stop generating findings for a specific control, we recommend disabling the control instead of using an automation rule. When you disable a control, Security Hub stops running security checks on it and stops generating findings for it, so you won't incur charges for that control. We recommend using automation rules to change the values of specific ASFF fields for findings that match defined criteria. For more information about disabling controls, see Configuring controls across standards.