Menu
AWS CloudTrail
User Guide (Version 1.0)

Using an AWS CloudFormation Template to Create CloudWatch Alarms

You can create CloudWatch metric filters and alarms that monitor the CloudTrail events that you specify and send you notifications when the events occur. You can create your filters and alarms separately, or by using an AWS CloudFormation template to define them all at once.

This topic describes an example CloudFormation template from AWS that you can use as is, or as a starting point or as a reference for creating your own templates. For information on creating CloudWatch metric filters and alarms individually, see Creating CloudWatch Alarms for CloudTrail Events: Examples.

The Example CloudFormation Template

The downloadable and editable example CloudFormation template from AWS contains predefined CloudWatch metric filters and alarms that enable you to receive email notifications when certain security-related API calls are made in your AWS account. You can download the template directly from the following link: https://s3-us-west-2.amazonaws.com/awscloudtrail/cloudwatch-alarms-for-cloudtrail-api-activity/CloudWatch_Alarms_for_CloudTrail_API_Activity.json.

The example template defines metric filters that monitor creation and deletion of, or updates to, security groups, network ACLs, internet gateways, Amazon EC2 instances, and IAM policies. For each filter, the template describes a corresponding alarm that enables to you to receive email notifications when a call to one of the APIs being monitored by the filter is made.

By default, most of the filters in the template trigger an alarm when one monitored event occurs within a five-minute period. You can modify these alarm thresholds for your own requirements. For example, you could monitor for 3 events in a 10-minute period. To make the changes, you can edit the template directly or, after following the steps in the section that follows (Using the CloudFormation template), you can alter the thresholds in the CloudWatch console.

Note

Because CloudTrail typically delivers log files every five minutes, it is highly recommended that you specify alarm periods of five minutes or more.

For a description of each of the metric filters and alarms in the template, and the API calls for which email notifications are triggered, see the section CloudFormation Template Contents later in this document.

Using the CloudFormation template

To use the template:

  1. Configure CloudTrail log file delivery to CloudWatch Logs. See Sending CloudTrail Events to CloudWatch Logs.

    Note

    If you change the default log group name provided by CloudTrail, note it so that you can use it in the next step.

  2. Create a AWS CloudFormation stack by using the template. A CloudFormation stack is a collection of related resources that you provision and update as a single unit.

The next section shows you how to create the stack and validate the email address that will receive any notifications that are generated.

Create a CloudFormation Stack

  1. Download the CloudFormation template from https://s3-us-west-2.amazonaws.com/awscloudtrail/cloudwatch-alarms-for-cloudtrail-api-activity/CloudWatch_Alarms_for_CloudTrail_API_Activity.json.

  2. Go to the CloudFormation console and create a new stack.

    AWS CloudFormation console
  3. On the Select Template page, give the stack a name. This example uses CloudWatchAlarmsForCloudTrail.

    Select Template page
  4. Under Template, select Upload a template to Amazon S3.

    Upload a template
  5. Click Choose File, and then browse to and select the CloudFormation template that you downloaded.

  6. Click Next.

  7. On the Specify Parameters page, provide the email address that will receive notifications, and the enter name of the log group name that you used when you configured CloudTrail log file delivery to CloudWatch Logs.

    Specify parameters
  8. Click Next.

  9. On the Options page, you can create tags or configure other advanced options. These are not required.

    Options page
  10. Click Next.

  11. On the Review page, verify that the template, email, log group, and other options, if any, are correct.

    Review page
  12. Click Create. The stack will be created in a few minutes.

    Stack create complete
  13. After the CloudFormation stack has been created, you will receive an email at the address that you specified to validate it.

  14. In the email, click Confirm subscription.

    Confirm subscription email

You will now receive email notifications when the alarms specified by the template are triggered.

Example email notification

You can review the metric filter or alarm definitions in the CloudWatch console.

CloudFormation Template Contents

The following tables show each of the metric filters and alarms in the template, their purpose, and the API calls for which email notifications are triggered. Notifications are triggered when one or more of the API calls for a listed filter are made.

Amazon S3 Bucket Events

Metric Filter and AlarmMonitor and Send Notifications forNotifications triggered by one or more of

S3BucketChangesMetricFilter

S3BucketChangesAlarm

API calls that change bucket policy, lifecycle, replication, or ACLs

PutBucketAcl

PutBucketPolicy

PutBucketCors

PutBucketLifecycle

PutBucketReplication

DeleteBucketPolicy

DeleteBucketCors

DeleteBucketLifecycle

DeleteBucketReplication


Network Events

Metric Filter and AlarmMonitor and Send Notifications forNotifications triggered by one or more of

SecurityGroupChangesMetricFilter

SecurityGroupChangesAlarm

API calls that create, update and delete Security Groups

AuthorizeSecurityGroupIngress

AuthorizeSecurityGroupEgress

RevokeSecurityGroupIngress

RevokeSecurityGroupEgress

CreateSecurityGroup

DeleteSecurityGroup

NetworkAclChangesMetricFilter

NetworkAclChangesAlarm

API calls that create, update and delete Network ACLs

CreateNetworkAcl

CreateNetworkAclEntry

DeleteNetworkAcl

DeleteNetworkAclEntry

ReplaceNetworkAclAssociation

ReplaceNetworkAclEntry

GatewayChangesMetricFilter

GatewayChangesAlarm

API calls that create, update and delete customer and Internet gateways

CreateCustomerGateway

DeleteCustomerGateway

AttachInternetGateway

CreateInternetGateway

DeleteInternetGateway

DetachInternetGateway

VpcChangesMetricFilter

VpcChangesAlarm

API calls that create, update and delete Virtual Private Clouds (VPCs), VPC peering connections and VPC connections to classic EC2 instances using ClassicLink

CreateVpc

DeleteVpc

ModifyVpcAttribute

AcceptVpcPeeringConnection

CreateVpcPeeringConnection

DeleteVpcPeeringConnection

RejectVpcPeeringConnection

AttachClassicLinkVpc

DetachClassicLinkVpc

DisableVpcClassicLink

EnableVpcClassicLink


Amazon EC2 Events

Metric Filter and AlarmMonitor and Send Notifications forNotifications triggered by one or more of

EC2InstanceChangesMetricFilter

EC2InstanceChangesAlarm

The creation, termination, start, stop, and reboot of EC2 instances

RebootInstances

RunInstances

StartInstances

StopInstances

TerminateInstances

EC2LargeInstanceChangesMetricFilter

EC2LargeInstanceChangesAlarm

The creation, termination, start, stop, and reboot of 4x and 8x large EC2 instances

At least one of

RebootInstances

RunInstances

StartInstances

StopInstances

TerminateInstances

and at least one of:

instancetype=*.4xlarge

instancetype=*.8xlarge


CloudTrail and IAM Events

Metric Filter and AlarmMonitor and Send Notifications forNotifications triggered by one or more of these calls (or activity)

CloudTrailChangesMetricFilter

CloudTrailChangesAlarm

The creation or deletion of trails, or updates to trails. The occurrence of start and stop logging events for a trail.

CreateTrail

DeleteTrail

StartLogging

StopLogging

UpdateTrail

ConsoleSignInFailuresMetricFilter

ConsoleSignInFailuresAlarm

Console login failures

eventName is ConsoleLogin and errorMessage is "Failed authentication"

AuthorizationFailuresMetricFilter

AuthorizationFailuresAlarm

Authorization failures

Any API call which results in an error code of AccessDenied or *UnauthorizedOperation.

IAMPolicyChangesMetricFilter

IAMPolicyChangesAlarm

Changes to IAM policies

DeleteGroupPolicy

DeleteRolePolicy

DeleteUserPolicy

PutGroupPolicy

PutRolePolicy

PutUserPolicy

CreatePolicy

DeletePolicy

CreatePolicyVersion

DeletePolicyVersion

AttachRolePolicy

DetachRolePolicy

AttachUserPolicy

DetachUserPolicy

AttachGroupPolicy

DetachGroupPolicy