Configuring an EventBridge rule for Security Hub findings
You can create a rule in Amazon EventBridge that defines an action to take when a Security Hub Findings - Imported event is
received. Security Hub Findings - Imported
events are triggered by updates from both the BatchImportFindings
and BatchUpdateFindings
operations.
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 (Security Hub Findings - Imported). 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 Security Hub Findings - Imported 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 Security Hub Findings - Imported events is as follows:
{ "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Imported" ], "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 adetail
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 Security Finding Format (ASFF) structure.
Tip
When filtering control findings, we recommend using the
SecurityControlId
or SecurityControlArn
ASFF fields as filters,
rather than Title
or Description
. The latter fields
can change occasionally, whereas the control ID and ARN are static
identifiers.
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": [ "Security Hub Findings - Imported" ], "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:
-
AwsAccountId
-
Compliance.Status
-
Criticality
-
ProductArn
-
RecordState
-
ResourceId
-
ResourceType
-
Severity.Label
-
Types
-
Workflow.Status
To create an EventBridge rule (console)
Open the Amazon EventBridge console at https://console.aws.amazon.com/events/
. -
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 Security Hub Findings - Imported.
-
(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": [ "Security Hub Findings - Imported" ], "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 verification state of
TRUE_POSITIVE
, use the following pattern example:{ "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Imported" ], "detail": { "findings": { "VerificationState": ["TRUE_POSITIVE"] } } }
-
-
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.
-