# Understanding automation rules in Security Hub CSPM
<a name="automation-rules"></a>

You can use automation rules to automatically update findings in AWS Security Hub CSPM. As it ingests findings, Security Hub CSPM 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 CSPM 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 CSPM. You can also start with a template and modify it as needed.

## Defining rule criteria and rule actions
<a name="automation-rules-how-it-works"></a>

From a Security Hub CSPM 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 CSPM applies the rule actions to it. For more information about available criteria and actions, see [Available rule criteria and rule actions](#automation-rules-criteria-actions).

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

The Security Hub CSPM 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 CSPM 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 CSPM console, Security Hub CSPM API, or [AWS CloudFormation](creating-resources-with-cloudformation.md).You can also use a [multi-Region deployment script](https://github.com/awslabs/aws-securityhub-multiaccount-scripts/blob/master/automation_rules).

## Available rule criteria and rule actions
<a name="automation-rules-criteria-actions"></a>

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


| Rule criterion | Filter operators | 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](https://docs.aws.amazon.com/securityhub/latest/userguide/asff-resources.html) 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 [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_StringFilter.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_StringFilter.html) in the *AWS Security Hub CSPM 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 [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_AutomationRulesFindingFilters.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_AutomationRulesFindingFilters.html) in the *AWS Security Hub CSPM 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](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html).

**Tip**  
 If you want Security Hub CSPM 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 CSPM 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 [Disabling controls in Security Hub CSPM](disable-controls-overview.md).

## Findings that automation rules evaluate
<a name="automation-rules-findings"></a>

An automation rule evaluates new and updated findings that Security Hub CSPM generates or ingests through the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchImportFindings.html](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.md).

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:
+ `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 [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html](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`.

1. If you call `GetFindings`, the `Workflow.Status` field now has a value of `NOTIFIED`.

1. 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.)

1. 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`.

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

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 [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_GetFindings.html](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).

## How rule order works
<a name="rule-order"></a>

When creating automation rules, you assign each rule an order. This determines the order in which Security Hub CSPM 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 CSPM console, Security Hub CSPM 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 CSPM applies subsequent rules in ascending order.

When you create a rule through the Security Hub CSPM API or AWS CLI, Security Hub CSPM 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 CSPM 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 CSPM`
  + `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 CSPM findings that match Rule A criteria. Next, Rule B actions apply to Security Hub CSPM 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`.