Automation rules

Automation rules can be used to automatically update findings in Security Hub. As findings are ingested, Security Hub can apply a variety of rule actions, such as suppressing findings, changing their severity, and adding notes to findings. Such rule actions take effect when findings match your specified criteria, such as which resource or account ID the finding is associated with or its title.

Examples of use cases for automation rules include:

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

Automation rules can be used to update select finding fields in the AWS Security Finding Format (ASFF). 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. If you use a rule template, you can modify it as needed for your use case.

How automation rules work

Only the Security Hub administrator account can create, delete, edit, and view automation rules. A rule that an administrator creates applies to findings in the administrator account and member accounts.

By defining member account IDs as criteria, Security Hub administrators can also use automation rules to update findings or take action on findings in specific member accounts.

You create an automation rule by defining criteria. When a finding matches the defined criteria, Security Hub applies the rule action to it. For more information about available criteria and actions, see Available rule criteria and rule actions.

Important

The delegated administrator must create an automation rule in each Region and account in which you want the rule to apply to findings, regardless of the rule criteria. To deploy a rule across multiple Regions, the delegated administrator can use a multi-Region automation rules deployment script. To deploy a rule across multiple accounts, the delegated administrator must manually create the rule in each account or write a script. Using an AWS CloudFormation template to create an automation rule can also make it simpler to deploy across multiple accounts and Regions. For more information, see Creating Security Hub resources with AWS CloudFormation.

To get a history of how automation rules have changed your findings, see Finding history.

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.

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

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 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]

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

• Confidence

• Criticality

• Note

• RelatedFindings

• Severity

• Types

• UserDefinedFields

• VertificationState

• 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 Enabling and disabling controls in all standards.

Creating automation rules

You can create a custom rule from scratch or use a pre-populated Security Hub rule template.

You can only create one automation rule at a time. To create multiple automation rules, follow the console procedures multiple times, or call the API or command multiple times with your desired parameters.

You must create an automation rule in each Region and account in which you want the rule to apply to findings.

When you create an automation rule in the Security Hub console, Security Hub shows you a preview of the findings to which your rule applies. The preview is currently not supported if your rule criteria include a CONTAINS or NOT_CONTAINS filter. You can choose these filters for map and string field types.

Important

AWS recommends that you don't include personally identifying, confidential, or sensitive information in your rule name, description, or other fields.

Creating a rule from a template (console only)

Currently, only the Security Hub console supports rule templates. These templates reflect common use cases for automation rules and can help you get started with the feature. Complete the following steps to create an automation rule from a template in the console.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Choose Create rule. For Rule Type , choose Create a rule from template.

4. Select a rule template from the drop down menu.

5. (Optional) If necessary for your use case, modify the Rule, Criteria, and Automated action sections. You must specify at least one rule criterion and one rule action.

   If supported for your selected criteria, the console shows you a preview of findings that match your criteria.

6. For Rule status, choose whether you want the rule to be Enabled or Disabled after it's created.

7. (Optional) Expand the Additional settings section. Select Ignore subsequent rules for findings that match these criteria if you want this rule to be the last rule applied to findings that match the rule criteria.

8. (Optional) For Tags, add tags as key-value pairs to help you easily identify the rule.

9. Choose Create rule.

Creating a custom rule

Choose your preferred method, and complete the following steps to create a custom automation rule.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Choose Create rule. For Rule Type , choose Create custom rule.

4. In the Rule section, provide a unique rule name and a description for your rule.

5. For Criteria, use the Key, Operator, and Value drop down menus to specify your rule criteria. You must specify at least one rule criterion.

   If supported for your selected criteria, the console shows you a preview of findings that match your criteria.

6. For Automated action, use the drop down menus to specify which finding fields to update when findings match your rule criteria. You must specify at least one rule action.

7. For Rule status, choose whether you want the rule to be Enabled or Disabled after it's created.

8. (Optional) Expand the Additional settings section. Select Ignore subsequent rules for findings that match these criteria if you want this rule to be the last rule applied to findings that match the rule criteria.

9. (Optional) For Tags, add tags as key-value pairs to help you easily identify the rule.

10. Choose Create rule.

API

1. Run CreateAutomationRule from the Security Hub administrator account. This API creates a rule with a specific Amazon Resource Name (ARN).

2. Provide a name and description for the rule.

3. Set the IsTerminal parameter to true if you want this rule to be the last rule applied to findings that match the rule criteria.

4. For the RuleOrder parameter, provide the order of the rule. Security Hub applies rules with a lower numerical value for this parameter first.

5. For the RuleStatus parameter, specify if you want Security Hub to enable and start applying the rule to findings after creation. If no value is specified, the default value is ENABLED. A value of DISABLED means that the rule is paused after creation.

6. For the Criteria parameter, provide the criteria that you want Security Hub to use to filter your findings. The rule action will apply to findings that match the criteria. For a list of supported criteria, see Available rule criteria and rule actions.

7. For the Actions parameter, provide the actions that you want Security Hub to take when there's a match between a finding and your defined criteria. For a list of supported actions, see Available rule criteria and rule actions.

Example API request:

{
    "Actions": [{
        "Type": "FINDING_FIELDS_UPDATE",
        "FindingFieldsUpdate": {
            "Workflow": {
                "Status": "SUPPRESSED"
            },
            "Note": {
                "Text": "Known issue that is not a risk.",
                "UpdatedBy": "sechub-automation"
            }
        }
    }],
    "Criteria": {
        "ProductName": [{
            "Value": "Security Hub",
            "Comparison": "EQUALS"
        }],
        "ComplianceStatus": [{
            "Value": "FAILED",
            "Comparison": "EQUALS"
        }],
        "RecordState": [{
            "Value": "ACTIVE",
            "Comparison": "EQUALS"
        }],
        "WorkflowStatus": [{
            "Value": "NEW",
            "Comparison": "EQUALS"
        }],
        "GeneratorId": [{
            "Value": "aws-foundational-security-best-practices/v/1.0.0/IAM.1",
            "Comparison": "EQUALS"
        }]
    },
    "Description": "Sample rule description",
    "IsTerminal": false,
    "RuleName": "sample-rule-name",
    "RuleOrder": 1,
    "RuleStatus": "ENABLED",
}

AWS CLI

1. Run the create-automation-rule command from the Security Hub administrator account. This command creates a rule with a specific Amazon Resource Name (ARN).

2. Provide a name and description for the rule.

3. Include the is-terminal parameter if you want this rule to be the last rule applied to findings that match the rule criteria. Otherwise, include the no-is-terminal parameter.

4. For the rule-order parameter, provide the order of the rule. Security Hub applies rules with a lower numerical value for this parameter first.

5. For the rule-status parameter, specify if you want Security Hub to enable and start applying the rule to findings after creation. If no value is specified, the default value is ENABLED. A value of DISABLED means that the rule is paused after creation.

6. For the criteria parameter, provide the criteria that you want Security Hub to use to filter your findings. The rule action will apply to findings that match the criteria. For a list of supported criteria, see Available rule criteria and rule actions.

7. For the actions parameter, provide the actions that you want Security Hub to take when there's a match between a finding and your defined criteria. For a list of supported actions, see Available rule criteria and rule actions.

Example command:

aws securityhub create-automation-rule \
--actions '[{
 "Type": "FINDING_FIELDS_UPDATE",
 "FindingFieldsUpdate": {
 "Severity": {
 "Label": "HIGH"
 },
 "Note": {
 "Text": "Known issue that is a risk. Updated by automation rules",
 "UpdatedBy": "sechub-automation"
 }
 }
 }]' \
--criteria '{
 "SeverityLabel": [{
 "Value": "INFORMATIONAL",
 "Comparison": "EQUALS"
 }]
 }' \
--description "A sample rule" \
--no-is-terminal \
--rule-name "sample rule" \
--rule-order 1 \
--rule-status "ENABLED" \
--region us-east-1

Viewing automation rules

Choose your preferred method, and follow the steps to view your automation rules and the details of each rule.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Choose a rule name. Alternatively, select a rule.

4. Choose Actions and View.

API

1. To view the automation rules for your account, run ListAutomationRules from the Security Hub administrator account. This API returns the rule ARNs and other metadata for your rules. No input parameters are required for this API, but you can optionally provide MaxResults to limit the number of results and NextToken as a pagination parameter. The initial value of NextToken should be NULL.

   Example API request:

   {
    "MaxResults": 50,
    "NextToken": "cVpdnSampleTokenYcXgTockBW44c"
   }

2. For additional rule details, including the criteria and actions for a rule, run BatchGetAutomationRules from the Security Hub administrator account.

   Example API request:

   {
       "AutomationRulesArns": [
         "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
         "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
         "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
         "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa"
       ]
   }

AWS CLI

1. To view the automation rules for your account, run the list-automation-rules command from the Security Hub administrator account. This command returns the rule ARNs and other metadata for your rules. No input parameters are required for this command, but you can optionally provide max-results to limit the number of results and next-token as a pagination parameter.

   Example command:

   aws securityhub list-automation-rules  \
   --max-results 5 \
   --next-token cVpdnSampleTokenYcXgTockBW44c \
   --region us-east-1
                               

2. For additional rule details, including the criteria and actions for a rule, run the batch-get-automation-rules command from the Security Hub administrator account.

   Example command:

   aws securityhub batch-get-automation-rules \
   --automation-rules-arns '["arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"]' \
   --region us-east-1

Editing automation rules

When you edit an automation rule, the changes apply to new and updated findings that Security Hub generates or ingests after the rule edit.

Choose your preferred method, and follow the steps to edit the contents of an automation rule. You can edit one or more rules with a single request. For instructions on editing rule order, see Editing rule order.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Select the rule that you want to edit. Choose Action and Edit.

4. Change the rule as desired, and choose Save changes.

API

1. Run BatchUpdateAutomationRules from the Security Hub administrator account.

2. For the RuleArn parameter, provide the ARN of the rule(s) that you want to edit.

3. Provide the new values for the parameters that you want to edit. You can edit any parameter except RuleArn.

Example API request:

{
    "UpdateAutomationRulesRequestItems": [
        {
            "RuleArn": "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "RuleOrder": 15,
            "RuleStatus": "Enabled"
        },
        {
            "RuleArn": "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
            "RuleStatus": "Disabled"
        }
    ]
}

AWS CLI

1. Run the batch-update-automation-rules command from the Security Hub administrator account.

2. For the RuleArn parameter, provide the ARN of the rule(s) that you want to edit.

3. Provide the new values for the parameters that you want to edit. You can edit any parameter except RuleArn.

Example command:

aws securityhub batch-update-automation-rules \
--update-automation-rules-request-items '[
    {
      "Actions": [{
        "Type": "FINDING_FIELDS_UPDATE",
        "FindingFieldsUpdate": {
          "Note": {
            "Text": "Known issue that is a risk",
            "UpdatedBy": "sechub-automation"
          },
          "Workflow": {
            "Status": "NEW"
          }
        }
      }],
      "Criteria": {
        "SeverityLabel": [{
         "Value": "LOW",
         "Comparison": "EQUALS"
        }]
      },
      "RuleArn": "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
      "RuleOrder": 14,
      "RuleStatus": "DISABLED",
    }
  ]' \
--region us-east-1

Editing rule order

In some cases, you might want to keep the rule criteria and actions as is, but change the order in which Security Hub applies an automation rule. Choose your preferred method, and follow the steps to edit rule order.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Select the rule whose order you want to change. Choose Edit priority.

4. Choose Move up to increase the rule's priority by one unit. Choose Move down to decrease the rule priority's by one unit. Choose Move to top to assign the rule an order of 1 (this gives the rule precedence over other existing rules).

Note

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.

API

1. Run BatchUpdateAutomationRules from the Security Hub administrator account.

2. For the RuleArn parameter, provide the ARN of the rule(s) whose order you want to edit.

3. Modify the value of the RuleOrder field.

Note

If multiple rules 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).

AWS CLI

1. Run the batch-update-automation-rules command from the Security Hub administrator account.

2. For the RuleArn parameter, provide the ARN of the rule(s) whose order you want to edit.

3. Modify the value of the RuleOrder field.

Note

If multiple rules 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).

Deleting automation rules

When you delete an automation rule, Security Hub removes it from your account and no longer applies the rule to findings.

Choose your preferred method, and follow the steps to delete an automation rule. You can delete one or more rules in a single request.

Tip

As an alternative to deletion, you can disable a rule. This retains the rule for future use, but Security Hub won't apply the rule to any matching findings until you enable it.

Console

1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

   Sign in to the Security Hub administrator account.

2. In the navigation pane, choose Automations.

3. Select the rule(s) that you want to delete. Choose Action and Delete (to retain a rule, but disable it temporarily, choose Disable).

4. Confirm your choice, and choose Delete.

API

1. Run BatchDeleteAutomationRules from the Security Hub administrator account.

2. For the AutomationRulesArns parameter, provide the ARN of the rule(s) that you want to delete (to retain a rule, but disable it temporarily, provide DISABLED for the RuleStatus parameter).

Example API request:

{
    "AutomationRulesArns": [
        "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
        "arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa"
    ]
}

AWS CLI

1. Run the batch-delete-automation-rules command from the Security Hub administrator account.

2. For the automation-rules-arns parameter, provide the ARN of the rule(s) that you want to delete (to retain a rule, but disable it temporarily, provide DISABLED for the RuleStatus parameter).

Example command:

aws securityhub batch-delete-automation-rules \
--automation-rules-arns '["arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"]' \
--region us-east-1

Automation rule examples

This section include some example automation rules for common use cases. These examples correspond to rule templates in the Security Hub console.

Elevate severity to Critical when specific resource such as an S3 bucket is at risk

In this example, the rule criteria are matched when the ResourceId in a finding is a specific Amazon Simple Storage Service (Amazon S3) bucket. The rule action is to change the severity of matched findings to CRITICAL. You can modify this template to apply to other resources.

Example API request:

{
    "IsTerminal": true,
    "RuleName": "Elevate severity of findings that relate to important resources",
    "RuleOrder": 1,
    "RuleStatus": "ENABLED",
    "Description": "Elevate finding severity to CRITICAL when specific resource such as an S3 bucket is at risk",
    "Criteria": {
        "ProductName": [{
            "Value": "Security Hub",
            "Comparison": "EQUALS"
        }],
        "ComplianceStatus": [{
            "Value": "FAILED",
            "Comparison": "EQUALS"
        }],
        "RecordState": [{
            "Value": "ACTIVE",
            "Comparison": "EQUALS"
        }],
        "WorkflowStatus": [{
            "Value": "NEW",
            "Comparison": "EQUALS"
        }],
        "ResourceId": [{
            "Value": "arn:aws:s3:::examplebucket/developers/design_info.doc",
            "Comparison": "EQUALS"
        }]
    },
    "Actions": [{
        "Type": "FINDING_FIELDS_UPDATE",
        "FindingFieldsUpdate": {
            "Severity": {
                "Label": "CRITICAL"
            },
            "Note": {
                "Text": "This is a critical resource. Please review ASAP.",
                "UpdatedBy": "sechub-automation"
            }
        }
    }]
}

Example CLI command:

aws securityhub create-automation-rule \
--is-terminal \
--rule-name "Elevate severity of findings that relate to important resources" \
--rule-order 1 \
--rule-status "ENABLED" \

--description "Elevate finding severity to CRITICAL when specific resource such as an S3 bucket is at risk" \
--criteria '{
"ProductName": [{
"Value": "Security Hub",
"Comparison": "EQUALS"
}],
"ComplianceStatus": [{
"Value": "FAILED",
"Comparison": "EQUALS"
}],
"RecordState": [{
"Value": "ACTIVE",
"Comparison": "EQUALS"
}],
"WorkflowStatus": [{
"Value": "NEW",
"Comparison": "EQUALS"
}],
"ResourceId": [{
"Value": "arn:aws:s3:::examplebucket/developers/design_info.doc",
"Comparison": "EQUALS"
}]
}' \
--actions '[{
"Type": "FINDING_FIELDS_UPDATE",
"FindingFieldsUpdate": {
"Severity": {
"Label": "CRITICAL"
},
"Note": {
"Text": "This is a critical resource. Please review ASAP.",
"UpdatedBy": "sechub-automation"
}
}
}]' \
--region us-east-1

Elevate severity of findings that relate to resources in production accounts

In this example, the rule criteria are matched when a HIGH severity finding is generated in specific production accounts. The rule action is to change the severity of matched findings to CRITICAL.

Example API request:

{
    "IsTerminal": false,
    "RuleName": "Elevate severity for production accounts",
    "RuleOrder": 1,
    "RuleStatus": "ENABLED",
    "Description": "Elevate finding severity from HIGH to CRITICAL for findings that relate to resources in specific production accounts",
    "Criteria": {
        "ProductName": [{
            "Value": "Security Hub",
            "Comparison": "EQUALS"
        }],
        "ComplianceStatus": [{
            "Value": "FAILED",
            "Comparison": "EQUALS"
        }],
        "RecordState": [{
            "Value": "ACTIVE",
            "Comparison": "EQUALS"
        }],
        "WorkflowStatus": [{
            "Value": "NEW",
            "Comparison": "EQUALS"
        }],
        "SeverityLabel": [{
            "Value": "HIGH",
            "Comparison": "EQUALS"
        }],
        "AwsAccountId": [
        {
            "Value": "111122223333",
            "Comparison": "EQUALS"
        },
        {
            "Value": "123456789012",
            "Comparison": "EQUALS"
        }]
    },
    "Actions": [{
        "Type": "FINDING_FIELDS_UPDATE",
        "FindingFieldsUpdate": {
            "Severity": {
                "Label": "CRITICAL"
            },
            "Note": {
                "Text": "A resource in production accounts is at risk. Please review ASAP.",
                "UpdatedBy": "sechub-automation"
            }
        }
    }]
}

Example CLI command:

aws securityhub create-automation-rule \
--no-is-terminal \
--rule-name "Elevate severity of findings that relate to resources in production accounts" \
--rule-order 1 \
--rule-status "ENABLED" \
--description "Elevate finding severity from HIGH to CRITICAL for findings that relate to resources in specific production accounts" \
--criteria '{
"ProductName": [{
"Value": "Security Hub",
"Comparison": "EQUALS"
}],
"ComplianceStatus": [{
"Value": "FAILED",
"Comparison": "EQUALS"
}],
"RecordState": [{
"Value": "ACTIVE",
"Comparison": "EQUALS"
}],
"SeverityLabel": [{
"Value": "HIGH",
"Comparison": "EQUALS"
}],
"AwsAccountId": [
{
"Value": "111122223333",
"Comparison": "EQUALS"
},
{
"Value": "123456789012",
"Comparison": "EQUALS"
}]
}' \
--actions '[{
"Type": "FINDING_FIELDS_UPDATE",
"FindingFieldsUpdate": {
"Severity": {
"Label": "CRITICAL"
},
"Note": {
"Text": "A resource in production accounts is at risk. Please review ASAP.",
"UpdatedBy": "sechub-automation"
}
}
}]' \
--region us-east-1

Suppress informational findings

In this example, the rule criteria are matched for INFORMATIONAL severity findings sent to Security Hub from Amazon GuardDuty. The rule action is to change the workflow status of matched findings to SUPPRESSED.

Example API request:

{
    "IsTerminal": false,
    "RuleName": "Suppress informational findings",
    "RuleOrder": 1,
    "RuleStatus": "ENABLED",
    "Description": "Suppress GuardDuty findings with INFORMATIONAL severity",
    "Criteria": {
        "ProductName": [{
            "Value": "GuardDuty",
            "Comparison": "EQUALS"
        }],
        "RecordState": [{
            "Value": "ACTIVE",
            "Comparison": "EQUALS"
        }],
        "WorkflowStatus": [{
            "Value": "NEW",
            "Comparison": "EQUALS"
        }],
        "SeverityLabel": [{
            "Value": "INFORMATIONAL",
            "Comparison": "EQUALS"
        }]
    },
    "Actions": [{
        "Type": "FINDING_FIELDS_UPDATE",
        "FindingFieldsUpdate": {
            "Workflow": {
                "Status": "SUPPRESSED"
            },
            "Note": {
                "Text": "Automatically suppress GuardDuty findings with INFORMATIONAL severity",
                "UpdatedBy": "sechub-automation"
            }
        }
    }]
}

Example CLI command:

aws securityhub create-automation-rule \
--no-is-terminal \
--rule-name "Suppress informational findings" \
--rule-order 1 \
--rule-status "ENABLED" \
--description "Suppress GuardDuty findings with INFORMATIONAL severity" \
--criteria '{
"ProductName": [{
"Value": "GuardDuty",
"Comparison": "EQUALS"
}],
"ComplianceStatus": [{
"Value": "FAILED",
"Comparison": "EQUALS"
}],
"RecordState": [{
"Value": "ACTIVE",
"Comparison": "EQUALS"
}],
"WorkflowStatus": [{
"Value": "NEW",
"Comparison": "EQUALS"
}],
"SeverityLabel": [{
"Value": "INFORMATIONAL",
"Comparison": "EQUALS"
}]
}' \
--actions '[{
"Type": "FINDING_FIELDS_UPDATE",
"FindingFieldsUpdate": {
"Workflow": {
"Status": "SUPPRESSED"
},
"Note": {
"Text": "Automatically suppress GuardDuty findings with INFORMATIONAL severity",
"UpdatedBy": "sechub-automation"
}
}
}]' \
--region us-east-1