Configuring rules for EventBridge

Note

Security Hub is in preview release and is subject to change.

You can create a rule in Amazon EventBridge that defines an action to take when a Findings Imported V2 event is received. Findings Imported V2 events are triggered by updates through BatchUpdateFindingsV2.

Each rule contains an event pattern, which identifies the events that trigger the rule. The event pattern always contains the event source (aws.securityhub) and the event type (Findings Imported V2). The event pattern can also specify filters to identify the findings that the rule applies to.

The event rule then identifies the rule targets. The targets are the actions to take when EventBridge receives a Findings Imported V2 event and the finding matches the filters.

The instructions provided here use the EventBridge console. When you use the console, EventBridge automatically creates the required resource-based policy that enables EventBridge to write to Amazon CloudWatch Logs.

You can also use the PutRule operation of the EventBridge API. However, if you use the EventBridge API, then you must create the resource-based policy. For information about the required policy, see CloudWatch Logs permissions in the Amazon EventBridge User Guide.

Format of the event pattern

The format of the event pattern for Findings Imported V2 events is as follows:

{
  "source": [
    "aws.securityhub"
  ],
  "detail-type": [
    "Findings Imported V2"
  ],
  "detail": {
    "findings": {
      <attribute filter values>
    }
  }
}

• source identifies Security Hub as the service that generates the event.

• detail-type identifies the type of event.

• detail is optional and provides the filter values for the event pattern. If the event pattern does not contain a detail field, then all findings trigger the rule.

You can filter the findings based on any finding attribute. For each attribute, you provide a comma-separated array of one or more values.

"<attribute name>": [ "<value1>", "<value2>"]

If you provide more than one value for an attribute, then those values are joined by OR. A finding matches the filter for an individual attribute if the finding has any of the listed values. For example, if you provide both INFORMATIONAL and LOW as values for Severity.Label, then the finding matches if it has a severity label of either INFORMATIONAL or LOW.

The attributes are joined by AND. A finding matches if it matches the filter criteria for all of the provided attributes.

When you provide an attribute value, it must reflect the location of that attribute within the AWS Open Cybersecurity Schema Framework (OCSF) structure.

In the following example, the event pattern provides filter values for ProductArn and Severity.Label, so a finding matches if it is generated by Amazon Inspector and it has a severity label of either INFORMATIONAL or LOW.

{
    "source": [
        "aws.securityhub"
     ],
    "detail-type": [
        "Findings Imported V2"
    ],
    "detail": {
        "findings": {
            "ProductArn": ["arn:aws:securityhub:us-east-1::product/aws/inspector"],
            "Severity": {
                "Label": ["INFORMATIONAL", "LOW"]
            }
        }
    }
}

Creating an event rule

You can use a predefined event pattern or a custom event pattern to create a rule in EventBridge. If you select a predefined pattern, EventBridge automatically fills in source and detail-type. EventBridge also provides fields to specify filter values for the following finding attributes:

• cloud.account.uid

• compliance.status

• metadata.product.name

• resources.uid

• severity

• status

To create an EventBridge rule (console)

1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

2. Using the following values, create an EventBridge rule that monitors finding events:

   • For Rule type, choose Rule with an event pattern.

   • Choose how to build the event pattern.

     To build the event pattern with...	Do this...
     A template	In the Event pattern section, choose the following options: For Event source, choose AWS services. For AWS service, choose Security Hub. For Event type, choose Findings Imported V2. (Optional) To make the rule more specific, add filter values. For example, to limit the rule to findings with active record states, for Specific Record state(s), choose Active.
     A custom event pattern (Use a custom pattern if you want to filter findings based on attributes that do not appear in the EventBridge console.)	In the Event pattern section, choose Custom patterns (JSON editor), and then paste the following event pattern into the text area: { "source": [ "aws.securityhub" ], "detail-type": [ "Findings Imported V2" ], "detail": { "findings": { "<attribute name>": [ "<value1>", "<value2>"] } } } Update the event pattern to include the attribute and attribute values that you want to use as a filter. For example, to apply the rule to findings that have a severity of Critical, use the following pattern example: { "source":["aws.securityhub"], "detail-type":["Findings Imported V2"], "detail":{ "findings":{ "Severity": ["Critical"] } } }

   • For Target types, choose AWS service, and for Select a target, choose a target such as an Amazon SNS topic or AWS Lambda function. The target is triggered when an event is received that matches the event pattern defined in the rule.

   For details about creating rules, see Creating Amazon EventBridge rules that react to events in the Amazon EventBridge User Guide.