AWS::SecurityHub::AutomationRule - AWS CloudFormation

AWS::SecurityHub::AutomationRule

The AWS::SecurityHub::AutomationRule resource specifies an automation rule based on input parameters. For more information, see Automation rules in the AWS Security Hub User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::SecurityHub::AutomationRule", "Properties" : { "Actions" : [ AutomationRulesAction, ... ], "Criteria" : AutomationRulesFindingFilters, "Description" : String, "IsTerminal" : Boolean, "RuleName" : String, "RuleOrder" : Integer, "RuleStatus" : String, "Tags" : {Key: Value, ...} } }

YAML

Type: AWS::SecurityHub::AutomationRule Properties: Actions: - AutomationRulesAction Criteria: AutomationRulesFindingFilters Description: String IsTerminal: Boolean RuleName: String RuleOrder: Integer RuleStatus: String Tags: Key: Value

Properties

Actions

One or more actions to update finding fields if a finding matches the conditions specified in Criteria.

Required: Yes

Type: Array of AutomationRulesAction

Minimum: 1

Maximum: 1

Update requires: No interruption

Criteria

A set of AWS Security Finding Format (ASFF) finding field attributes and corresponding expected values that Security Hub uses to filter findings. If a rule is enabled and a finding matches the criteria specified in this parameter, Security Hub applies the rule action to the finding.

Required: Yes

Type: AutomationRulesFindingFilters

Update requires: No interruption

Description

A description of the rule.

Required: Yes

Type: String

Minimum: 1

Maximum: 1024

Update requires: No interruption

IsTerminal

Specifies whether a rule is the last to be applied with respect to a finding that matches the rule criteria. This is useful when a finding matches the criteria for multiple rules, and each rule has different actions. If a rule is terminal, Security Hub applies the rule action to a finding that matches the rule criteria and doesn't evaluate other rules for the finding. By default, a rule isn't terminal.

Required: No

Type: Boolean

Update requires: No interruption

RuleName

The name of the rule.

Required: Yes

Type: String

Minimum: 1

Maximum: 256

Update requires: No interruption

RuleOrder

An integer ranging from 1 to 1000 that represents the order in which the rule action is applied to findings. Security Hub applies rules with lower values for this parameter first.

Required: Yes

Type: Integer

Minimum: 1

Maximum: 1000

Update requires: No interruption

RuleStatus

Whether the rule is active after it is created. If this parameter is equal to ENABLED, Security Hub applies the rule to findings and finding updates after the rule is created.

Required: No

Type: String

Allowed values: ENABLED | DISABLED

Update requires: No interruption

Tags

User-defined tags associated with an automation rule.

Required: No

Type: Object of String

Pattern: ^[a-zA-Z0-9]{1,128}$

Minimum: 0

Maximum: 256

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns RuleArn. For example, arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

CreatedAt

A timestamp that indicates when the rule was created.

Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

CreatedBy

The principal that created the rule. For example, arn:aws:sts::123456789012:assumed-role/Developer-Role/JaneDoe.

RuleArn

The Amazon Resource Name (ARN) of the automation rule that you create. For example, arn:aws:securityhub:us-east-1:123456789012:automation-rule/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111.

UpdatedAt

A timestamp that indicates when the rule was most recently updated.

Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

Examples

The following examples demonstrate how to declare an AWS::SecurityHub::AutomationRule resource.

Creating an automation rule

This example creates a Security Hub automation rule. This example contains all available fields for Actions and Criteria for demonstration purposes.

JSON

{ "Description": "Example template to create a Security Hub automation rule", "Resources": { "RuleWithCriteriaActionsTags": { "Type": "AWS::SecurityHub::AutomationRule", "Properties": { "RuleName": "Example rule name", "RuleOrder": 5, "Description": "Example rule description.", "IsTerminal": false, "RuleStatus": "ENABLED", "Criteria": { "ProductName": [ { "Comparison": "EQUALS", "Value": "GuardDuty" }, { "Comparison": "PREFIX", "Value": "SecurityHub" } ], "CompanyName": [ { "Comparison": "EQUALS", "Value": "AWS" }, { "Comparison": "PREFIX", "Value": "Private" } ], "ProductArn": [ { "Comparison": "EQUALS", "Value": "arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default" }, { "Comparison": "PREFIX", "Value": "arn:aws:securityhub:us-west-2:123456789012:product/aws" } ], "AwsAccountId": [ { "Comparison": "EQUALS", "Value": 123456789012 } ], "Id": [ { "Comparison": "EQUALS", "Value": "example-finding-id" } ], "GeneratorId": [ { "Comparison": "EQUALS", "Value": "example-generator-id" } ], "Type": [ { "Comparison": "EQUALS", "Value": "type-1" }, { "Comparison": "EQUALS", "Value": "type-2" } ], "Description": [ { "Comparison": "EQUALS", "Value": "description1" }, { "Comparison": "EQUALS", "Value": "description2" } ], "SourceUrl": [ { "Comparison": "PREFIX", "Value": "https" }, { "Comparison": "PREFIX", "Value": "ftp" } ], "Title": [ { "Comparison": "EQUALS", "Value": "title-1" }, { "Comparison": "PREFIX", "Value": "title-2" } ], "SeverityLabel": [ { "Comparison": "EQUALS", "Value": "LOW" }, { "Comparison": "EQUALS", "Value": "HIGH" } ], "ResourceType": [ { "Comparison": "EQUALS", "Value": "AwsEc2Instance" } ], "ResourcePartition": [ { "Comparison": "EQUALS", "Value": "aws" } ], "ResourceId": [ { "Comparison": "PREFIX", "Value": "i-1234567890" } ], "ResourceRegion": [ { "Comparison": "PREFIX", "Value": "us-west" } ], "ComplianceStatus": [ { "Comparison": "EQUALS", "Value": "FAILED" } ], "ComplianceSecurityControlId": [ { "Comparison": "EQUALS", "Value": "EC2.3" } ], "ComplianceAssociatedStandardsId": [ { "Comparison": "EQUALS", "Value": "ruleset/cis-aws-foundations-benchmark/v/1.2.0" } ], "VerificationState": [ { "Comparison": "EQUALS", "Value": "BENIGN_POSITIVE" } ], "RecordState": [ { "Comparison": "EQUALS", "Value": "ACTIVE" } ], "RelatedFindingsProductArn": [ { "Comparison": "EQUALS", "Value": "arn:aws:securityhub:eu-central-1::product/aws/securityhub" } ], "RelatedFindingsId": [ { "Comparison": "EQUALS", "Value": "example-finding-id-2" } ], "NoteText": [ { "Comparison": "EQUALS", "Value": "example-note-text" } ], "NoteUpdatedAt": [ { "DateRange": { "Unit": "DAYS", "Value": 5 } } ], "NoteUpdatedBy": [ { "Comparison": "PREFIX", "Value": "sechub" } ], "WorkflowStatus": [ { "Comparison": "EQUALS", "Value": "NEW" } ], "FirstObservedAt": [ { "DateRange": { "Unit": "DAYS", "Value": 5 } } ], "LastObservedAt": [ { "DateRange": { "Unit": "DAYS", "Value": 5 } } ], "CreatedAt": [ { "DateRange": { "Unit": "DAYS", "Value": 5 } } ], "UpdatedAt": [ { "Start": "2023-04-25T17:05:54.832Z", "End": "2023-05-25T17:05:54.832Z" } ], "ResourceTags": [ { "Comparison": "NOT_EQUALS", "Key": "department", "Value": "security" }, { "Comparison": "NOT_EQUALS", "Key": "department", "Value": "operations" } ], "UserDefinedFields": [ { "Comparison": "EQUALS", "Key": "key1", "Value": "security" }, { "Comparison": "EQUALS", "Key": "key2", "Value": "operations" } ], "ResourceDetailsOther": [ { "Comparison": "NOT_EQUALS", "Key": "area", "Value": "na" }, { "Comparison": "NOT_EQUALS", "Key": "department", "Value": "sales" } ], "Confidence": [ { "Gte": 50, "Lte": 95 } ], "Criticality": [ { "Gte": 50, "Lte": 95 } ] }, "Actions": [ { "Type": "FINDING_FIELDS_UPDATE", "FindingFieldsUpdate": { "Severity": { "Product": 50, "Label": "MEDIUM", "Normalized": 60 }, "Types": [ "Software and Configuration Checks/Industry and Regulatory Standards/AWS-Foundational-Security-Best-Practices", "Industry Compliance" ], "Confidence": 98, "Criticality": 95, "UserDefinedFields": { "key1": "value1", "key2": "value2" }, "RelatedFindings": [ { "ProductArn": "arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default", "Id": "sample-finding-id-1" }, { "ProductArn": "arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default", "Id": "sample-finding-id-2" } ], "Note": { "Text": "sample-note-text", "UpdatedBy": "sechub" }, "VerificationState": "TRUE_POSITIVE", "Workflow": { "Status": "NOTIFIED" } } } ], "Tags": { "sampleTag": "sampleValue", "organizationUnit": "pnw" } } } } }

YAML

Description: Example template to create a Security Hub automation rule Resources: RuleWithCriteriaActionsTags: Type: "AWS::SecurityHub::AutomationRule" Properties: RuleName: "Example rule name" RuleOrder: 5 Description: "Example rule description." IsTerminal: false RuleStatus: "ENABLED" Criteria: ProductName: - Comparison: EQUALS Value: GuardDuty - Comparison: PREFIX Value: SecurityHub CompanyName: - Comparison: EQUALS Value: AWS - Comparison: PREFIX Value: Private ProductArn: - Comparison: EQUALS Value: arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default - Comparison: PREFIX Value: arn:aws:securityhub:us-west-2:123456789012:product/aws AwsAccountId: - Comparison: EQUALS Value: 123456789012 Id: - Comparison: EQUALS Value: example-finding-id GeneratorId: - Comparison: EQUALS Value: example-generator-id Type: - Comparison: EQUALS Value: type-1 - Comparison: EQUALS Value: type-2 Description: - Comparison: EQUALS Value: description1 - Comparison: EQUALS Value: description2 SourceUrl: - Comparison: PREFIX Value: https - Comparison: PREFIX Value: ftp Title: - Comparison: EQUALS Value: title-1 - Comparison: PREFIX Value: title-2 SeverityLabel: - Comparison: EQUALS Value: LOW - Comparison: EQUALS Value: HIGH ResourceType: - Comparison: EQUALS Value: AwsEc2Instance ResourcePartition: - Comparison: EQUALS Value: aws ResourceId: - Comparison: PREFIX Value: i-1234567890 ResourceRegion: - Comparison: PREFIX Value: us-west ComplianceStatus: - Comparison: EQUALS Value: FAILED ComplianceSecurityControlId: - Comparison: EQUALS Value: EC2.3 ComplianceAssociatedStandardsId: - Comparison: EQUALS Value: ruleset/cis-aws-foundations-benchmark/v/1.2.0 VerificationState: - Comparison: EQUALS Value: BENIGN_POSITIVE RecordState: - Comparison: EQUALS Value: ACTIVE RelatedFindingsProductArn: - Comparison: EQUALS Value: arn:aws:securityhub:eu-central-1::product/aws/securityhub RelatedFindingsId: - Comparison: EQUALS Value: example-finding-id-2 NoteText: - Comparison: EQUALS Value: example-note-text NoteUpdatedAt: - DateRange: Unit: DAYS Value: 5 NoteUpdatedBy: - Comparison: PREFIX Value: sechub WorkflowStatus: - Comparison: EQUALS Value: NEW FirstObservedAt: - DateRange: Unit: DAYS Value: 5 LastObservedAt: - DateRange: Unit: DAYS Value: 5 CreatedAt: - DateRange: Unit: DAYS Value: 5 UpdatedAt: - Start: "2023-04-25T17:05:54.832Z" End: "2023-05-25T17:05:54.832Z" ResourceTags: - Comparison: NOT_EQUALS Key: department Value: security - Comparison: NOT_EQUALS Key: department Value: operations UserDefinedFields: - Comparison: EQUALS Key: key1 Value: security - Comparison: EQUALS Key: key2 Value: operations ResourceDetailsOther: - Comparison: NOT_EQUALS Key: area Value: na - Comparison: NOT_EQUALS Key: department Value: sales Confidence: - Gte: 50 Lte: 95 Criticality: - Gte: 50 Lte: 95 Actions: - Type: FINDING_FIELDS_UPDATE FindingFieldsUpdate: Severity: Product: 50 Label: MEDIUM Normalized: 60 Types: - Software and Configuration Checks/Industry and Regulatory Standards/AWS-Foundational-Security-Best-Practices - Industry Compliance Confidence: 98 Criticality: 95 UserDefinedFields: key1: value1 key2: value2 RelatedFindings: - ProductArn: arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default Id: sample-finding-id-1 - ProductArn: arn:aws:securityhub:us-west-2:123456789012:product/123456789012/default Id: sample-finding-id-2 Note: Text: sample-note-text UpdatedBy: sechub VerificationState: TRUE_POSITIVE Workflow: Status: NOTIFIED Tags: sampleTag: sampleValue organizationUnit: pnw