AWS CloudTrail Event Trigger

Overview

The CloudTrail Event trigger responds to specific events recorded in AWS CloudTrail. The trigger activates when it detects the chosen CloudTrail event name(s) and, if specified, the event source(s).

When paired with an Action and configurable event matching, you can enhance security, streamline operations and reduce manual intervention.

Understanding CloudTrail and the trigger

CloudTrail is typically used in the governance and auditing of an AWS Account. It captures the details of every API request in your AWS account, including some non-API service events.

When CloudTrail is enabled, its events are also sent to the CloudWatch Event Bus, which is the default Event Bus on AWS Event Bridge. When you create or enable a GorillaStack rule with the CloudTrail Event Trigger, the Event Bus is configured to forward events from CloudTrail via the default Event Bus in your account to GorillaStack.

Although CloudTrail captures every API request in an AWS account and records them to S3, only write API requests are sent as CloudWatch events. Describe* events are not sent over the CloudWatch event bus, and therefore cannot be used to trigger a GorillaStack rule.

AWS account permissions

The CloudTrail Event trigger uses the following endpoints on AWS’s EventBridge API:

The GorillaStack cross-account role needs permission to use these endpoints.

Use of this trigger in a rule

The CloudTrail Event trigger will usually be used in a rule with the Notify on CloudTrail Event action, which generates formatted notifications based on selected events. However, it is possible to pair it with any action.

For example, this rule notifies you immediately when AutoScaling Group settings are changed, then waits 10 minutes for any changes to your EC2 instance count to flow through, then notifies you of the new instance count:

Configuration

The trigger works by matching fields in a CloudTrail record event after it is received on the CloudWatch Event Bus. See the AWS Documentation for a full description of the available fields.

You can match the record on the following fields directly:

Event Name (mandatory)

This is usually the name of the API Action (e.g. this would be CreateBucket for a bucket creation event in S3), but can vary for some scenarios (see Identifying CloudTrail Event Names below).
Event Source

This is the dotted domain name of the event. This is not required, but may be used to restrict the events received when the same (unrelated) Event Name appears in multiple event sources.

In each of the above fields, an exact match is performed (i.e. these are case sensitive and cannot use wildcards). You may list multiple Event Names and/or Event Sources. A match on any of the listed entries will activate the Trigger.

In addition, you may optionally specify a Match Expression. This is a JMESPath expression that will be evaluated against the event to determine if the trigger should fire. (See the GorillaStack-maintained fork of the JMESPath specification for documentation.) It is tested after the Event Name, so it may only be used as a further restricting condition, not as an alternative to Event Name.

Identifying CloudTrail Event Names

Almost everything that occurs in your AWS account is reported as a CloudTrail event. Use this field to list just the specific event types you are interested in.

There is no comprehensive list of CloudTrail event names available at present. However, most of the API endpoints listed in AWS’s documentation generate a CloudTrail event that has the same name as the endpoint. For example, when the CopySnapshots endpoint on the EC2 API is called, a CopySnapshots event is generated. One notable exception to this rule-of-thumb is the Describe* endpoints, which generally do not create monitorable events. To be sure of what events are available to you, log into CloudTrail in the AWS Console, then click Event History.

Identifying CloudTrail Event Sources

The Event Source is usually the short name of the AWS service combined in the form:

<event_source>.amazonaws.com

e.g. iam.amazonaws.com, ec2.amazonaws.com, monitoring.amazonaws.com

(Note that there is no region specified. GorillaStack filters the region as per the Context configured in the GorillaStack rule.)

Specifying a Match Expression

The Match Expression is tested against any of the event fields, and it must evaluate to true in order to pass the evaluation. This means any value that is true when coerced to a boolean in JavaScript. For example:

null, undefined, empty string ('') and 0 are always converted to false
non-empty strings (including those with whitespace), empty arrays ([]), empty objects ({}) and non-zero numbers are converted to true

Use one of the example objects to get an idea of the event structure of a CloudTrail via CloudWatch event. Be aware that the CloudTrail event data is stored in the detail field of the CloudWatch event, and that the detail field must be specified in full to match against its fields.

Here are some example expressions that might be useful:

S3 CreateBucket events, where the bucket name does not have the right prefix

!starts_with(detail.requestParameters.bucketName, 'gorillastack-')
Non-MFA authenticated access (note that the value is expressed as a string, which is why it is surrounded by quote marks)

detail.userIdentity.sessionContext.attributes.mfaAuthenticated == 'false'
Launch of an unencrypted instance on RDS (note that the value is expressed as a boolean, which is why it is surrounded by backticks)

detail.requestParameters.storageEncrypted == `false`
Event occurred using the AWS S3 Console

contains(detail.userAgent, 'S3Console')
Root user access

detail.userIdentity.type == 'Root'
Source IP Address not in subnet

!starts_with(detail.sourceIPAddress, '55.10.15.')