How can I create an Amazon EventBridge rule to automate responses to CloudTrail API calls?

Short description

You can configure a custom action or notification for an AWS CloudTrail API call. To do so, create an Amazon EventBridge rule with an event pattern to match the CloudTrail event. Because Amazon EventBridge accommodates up to five targets, your rule can have multiple targets.

Use the following targets for your action:

• An AWS Lambda function to run custom actions or automation
• An Amazon CloudWatch Log group to record matching CloudTrail events

Resolution

As a first step, make sure that you are capturing events in CloudTrail. You can then forward these events to Amazon EventBridge.
Note: You can't capture events without first configuring a CloudTrail trail. The EventBridge rule doesn't trigger without a trail, even when you have a valid event pattern match.

Create a CloudTrail trail

If you haven't set up CloudTrail to capture events, complete these steps:

1. Open the AWS CloudTrail console.
2. Navigate to Trails on the left hand pane.
3. Verify whether a trail already exists in the Region you are creating your rule in. If yes, then make sure that the status is set to Logging
4. If you don't have an existing trail, select Create trail.
5. For Trail name, enter a name.
6. For Storage location, select Create a new S3 bucket.
7. For AWS KMS alias, enter an alias for the AWS Key Management Service (AWS KMS) key.
8. Choose Next. Then, choose Next again.
9. Choose Create trail.

For more information, see Creating a trail.

Create an EventBridge rule and event pattern

This example uses a Simple Queue Service (Amazon SQS) API, CreateQueue, to generate an event. When the SQS API is called, CloudTrail records the generated event. Then, CloudTrail forwards the event to the default EventBridge bus.

Create a rule and event pattern

1. Open the Amazon EventBridge console.

2. In the navigation pane, choose Rules.

3. Choose Create rule.

4. Enter a name and description for the rule. For example, name the rule TestRule.

5. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an AWS service in your account creates an event, the event always goes to your account's default event bus.

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

7. Choose Next.

8. For Event source, choose AWS services.

9. For Event pattern, select these options:
   For Event source, select SQS from the dropdown list.
   For Event type, select AWS API Call via CloudTrail from the dropdown list.
   Choose Specific operation(s), and then enter CreateQueue.

   This example shows the event pattern that results from these options. The pattern filters on a number of fields, such as eventName and eventSource. An event match must contain all the fields and corresponding values.

   {
     "source": ["aws.sqs"],
     "detail-type": ["AWS API Call via CloudTrail"],
     "detail": {
       "eventSource": ["sqs.amazonaws.com"],
       "eventName": ["CreateQueue"]
     }
   }

10. Choose Next.

Associate targets

Associate target types for the rule. Continue to configure as follows:

1. For Target types, choose AWS service.
2. For Select a target, choose Lambda function from the dropdown list.
3. Choose the Function of your choice under the dropdown list.
4. Select Add another target, and then select CloudWatch log group under AWS service.
5. Select an existing log group from the Select log group dropdown list, or create a new log group.
6. Choose Next. Then, choose Next again.
7. Review the details of the rule, and then choose Create rule.

Validate the EventBridge rule

1. Generate the API call:
   Navigate to the Amazon SQS console.
   Choose Create queue.
   For Type, leave the Standard queue type as default.
   Enter a Name for your queue.
   Leave all other options as default, and then select Create queue.
2. Confirm that the EventBridge rule triggered and invoked the targets using TriggeredRules, Invocations, and FailedInvocations metrics. These metrics are available in the EventBridge console. Navigate to the rule that you created and then open the Monitoring tab to view the metrics. Or, view the metrics in the CloudWatch console under the AWS/Events namespace.
3. Confirm that the Lambda function was successfully invoked.
4. Confirm that the CloudWatch log group captured the event. Navigate to your target log group in the CloudWatch Logs console. Note that a new log stream is visible with the corresponding log event.

Related information

Tutorial: Log AWS API calls using EventBridge

How can I create a custom event pattern for an EventBridge rule?