Prerequisites
Before you begin, you must complete the following prerequisites and setup:
• Create an AWS account, if you do not already have one.
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
• Create an IAM user for administering CloudTrail. For more information, see Granting permissions for CloudTrail administration (p. 269).
Step 1: Review AWS account activity in event history
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in any AWS service that supports CloudTrail, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. In other words, you can view, search, and download recent events in your AWS account before creating a trail, though creating a trail is important for long-term records and
Step 1: Review AWS account activity in event history
auditing of your AWS account activity. Unlike a trail, Event history only shows events that have occurred over the last 90 days.
1. Sign in to the AWS Management Console using the IAM user you configured for CloudTrail
administration. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/home/.
2. Review the information in your dashboard about the most recent events that have occurred in your AWS account. A recent event should be a ConsoleLogin event, showing that you just signed in to the AWS Management Console.
3. To see more information about an event, expand it.
4. In the navigation pane, choose Event history. You see a filtered list of events, with the most recent events showing first. The default filter for events is Read only, set to false. You can clear that filter by choosing X at the right of the filter.
5. Many more events are shown without the default filter. You can filter events in many ways. For example, to view all console login events, you could choose the Event name filter, and specify ConsoleLogin. The choice of filters is up to you.
Step 2: Create your first trail
6. You can save event history by downloading it as a file in CSV or JSON format. Downloading your event history can take a few minutes.
For more information, see Viewing events with CloudTrail Event history (p. 44).
Step 2: Create your first trail
While the events provided in Event history in the CloudTrail console are useful for reviewing recent activity, they are limited to recent activity, and they do not include all possible events that can be recorded by CloudTrail. Additionally, your view of events in the console is limited to the AWS Region where you are signed in. To create an ongoing record of activity in your AWS account that captures information for all AWS Regions, create a trail. By default, when you create a trail in the CloudTrail console, the trail logs events in all Regions. Logging events in all Regions in your account is a recommended best practice.
For your first trail, we recommend creating a trail that logs all management events (p. 5) in all AWS Regions, and does not log any data events (p. 5). Examples of management events include security events such as IAM CreateUser and AttachRolePolicy events, resource events such as RunInstances and CreateBucket, and many more. You will create an Amazon S3 bucket where you will store the log files for the trail as part of creating the trail in the CloudTrail console.
NoteThis tutorial assumes you are creating your first trail. Depending on the number of trails you have in your AWS account, and how those trails are configured, the following procedure might or might not incur expenses. CloudTrail stores log files in an Amazon S3 bucket, which incurs costs. For more information about pricing, see AWS CloudTrail Pricing and Amazon S3 Pricing.
1. Sign in to the AWS Management Console using the IAM user you configured for CloudTrail
administration. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/home/.
In the Region selector, choose the AWS Region where you want your trail to be created. This is the home Region for the trail.
NoteThe home Region is the only AWS Region where you can view and update the trail after it is created, even if the trail logs events in all AWS Regions.
Step 2: Create your first trail
2. On the CloudTrail service home page, the Trails page, or the Trails section of the Dashboard page, choose Create trail.
3. In Trail name, give your trail a name, such as My-Management-Events-Trail. As a best practice, use a name that quickly identifies the purpose of the trail. In this case, you're creating a trail that logs management events.
4. Leave default settings for AWS Organizations organization trails. This option won't be available to change unless you have accounts configured in Organizations.
5. For Storage location, choose Create new S3 bucket to create a bucket. When you create a bucket, CloudTrail creates and applies the required bucket policies. Give your bucket a name, such as my-bucket-for-storing-cloudtrail-logs.
To make it easier to find your logs, create a new folder (also known as a prefix) in an existing bucket to store your CloudTrail logs. Enter the prefix in Prefix.
Note
The name of your Amazon S3 bucket must be globally unique. For more information, see Amazon S3 bucket naming requirements (p. 134).
6. Clear the check box to disable Log file SSE-KMS encryption. By default, your log files are encrypted with SSE-S3 encryption. For more information about this setting, see Protecting Data Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3).
7. Leave default settings in Additional settings.
8. For now, do not send logs to Amazon CloudWatch Logs.
9. In Tags, add one or more custom tags (key-value pairs) to your trail. Tags can help you identify your CloudTrail trails and other resources, such as the Amazon S3 buckets that contain CloudTrail log files. For example, you could attach a tag with the name Compliance and the value Auditing.
NoteThough you can add tags to trails when you create them in the CloudTrail console, and you can create an Amazon S3 bucket to store your log files in the CloudTrail console, you cannot
Step 2: Create your first trail
add tags to the Amazon S3 bucket from the CloudTrail console. For more information about viewing and changing the properties of an Amazon S3 bucket, including adding tags to a bucket, see the Amazon S3 User Guide.
When you are finished creating tags, choose Next.
10. On the Choose log events page, select event types to log. For this trail, keep the default,
Management events. In the Management events area, choose to log both Read and Write events, if they are not already selected. Leave the check boxes for Exclude AWS KMS events and Exclude Amazon RDS Data API events empty, to log all events.
Step 3: View your log files
11. Leave default settings for Data events and Insights events. This trail will not log any data or CloudTrail Insights events. Choose Next.
12. On the Review and create page, review the settings you've chosen for your trail. Choose Edit for a section to go back and make changes. When you are ready to create your trail, choose Create trail.
13. The Trails page shows your new trail in the table. Note that the trail is set to Multi-region trail by default, and that logging is turned on for the trail by default.
Step 3: View your log files
Within an average of about 15 minutes of creating your first trail, CloudTrail delivers the first set of log files to the Amazon S3 bucket for your trail. You can look at these files and learn about the information they contain.
Note
CloudTrail typically delivers logs within an average of about 15 minutes of an API call. This time is not guaranteed. Review the AWS CloudTrail Service Level Agreement for more information.
1. In the navigation pane, choose Trails. On the Trails page, find the name of the trail you just created (in the example, My-Management-Events-Trail).
Step 3: View your log files
NoteBe sure you are still signed in using the IAM user you configured for CloudTrail
administration. Otherwise you might not have sufficient permissions to view trails in the CloudTrail console or the Amazon S3 bucket that contains log files for that trail.
2. In the row for the trail, choose the value for the S3 bucket (in the example, aws-cloudtrail-logs-08132020-mytrail).
3. The Amazon S3 console opens and shows that bucket, at the top level for log files. Because you created a trail that logs events in all AWS Regions, the display opens at the level that shows you each Region folder. The hierarchy of the Amazon S3 bucket navigation at this level is bucket-name/ AWSLogs/account-id/CloudTrail. Choose the folder for the AWS Region where you want to review log files. For example, if you want to review the log files for the US East (Ohio) Region, choose us-east-2.
4. Navigate the bucket folder structure to the year, the month, and the day where you want to review logs of activity in that Region. In that day, there are a number of files. The name of the files begin with your AWS account ID, and end with the extension .gz. For example, if your account ID is 123456789012, you would see files with names similar to this: 123456789012_CloudTrail_ us-east-2_20190610T1255abcdeEXAMPLE.json.gz.
To view these files, you can download them, unzip them, and then view them in a plain-text editor or a JSON file viewer. Some browsers also support viewing .gz and JSON files directly. We recommend using a JSON viewer, as it makes it easier to parse the information in CloudTrail log files.
As you're browsing through the file content, you might start to wonder about what you're seeing.
CloudTrail logs events for every AWS service that experienced activity in that AWS Region at the time that event occurred. In other words, events for different AWS services are mixed together, based solely on time. To learn more about what a specific AWS service logs with CloudTrail, including examples of log file entries for API calls for that service, see the list of supported services for CloudTrail (p. 22), and read the CloudTrail integration topic for that service. You can also learn more about the content and structure of CloudTrail log files by reviewing the CloudTrail log event reference (p. 304).
You might also notice what you're not seeing in log files in US East (Ohio). Specifically, you won't see any console sign-in events, even though you know you logged into the console. That's because console sign-in and IAM events are global service events (p. 11), which are usually logged in a specific AWS Region. In this case, they are logged in US East (N. Virginia), and found in the folder us-east-1. Open that folder, and open the year, month, and day you're interested in. Browse the log files, and you find ConsoleLogin events that look similar to the following:
{
"eventVersion": "1.05", "userIdentity": { "type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
Step 4: Plan for next steps
"arn": "arn:aws:iam::123456789012:user/Mary_Major", "accountId": "123456789012",
"userName": "Mary_Major"
},
"eventTime": "2019-06-10T17:14:09Z", "eventSource": "signin.amazonaws.com", "eventName": "ConsoleLogin",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.67",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
"requestParameters": null, "responseElements": {
"ConsoleLogin": "Success"
},
"additionalEventData": {
"LoginTo": "https://console.aws.amazon.com/console/home?state=hashArgs
%23&isauthcode=true",
"MobileVersion": "No", "MFAUsed": "No"
},
"eventID": "2681fc29-EXAMPLE", "eventType": "AwsConsoleSignIn", "recipientAccountId": "123456789012"
}
This log file entry tells you more than just the identity of the IAM user who logged in (Mary_Major), the date and time she logged in, and that the login was successful. You can also learn the IP address she logged in from, the operating system and browser software of the computer she used, and that she was not using multi-factor authentication.
Step 4: Plan for next steps
Now that you have a trail, you have access to an ongoing record of events and activities in your AWS account. This ongoing record helps you meet accounting and auditing needs for your AWS account.
However, there is a lot more you can do with CloudTrail and CloudTrail data.
• Add additional security for your trail data. CloudTrail automatically applies a certain level of security when you create a trail. However, there are additional steps you can take to help keep your data secure.
• By default, the Amazon S3 bucket you created as part of creating a trail has a policy applied that allows CloudTrail to write log files to that bucket. The bucket is not publicly accessible, but it might be accessible to other users in your AWS account if they have permissions to read and write to buckets in your AWS account. Review the policy for your bucket and if necessary, make changes to restrict access to a specific set of IAM users. For more information, see the Amazon S3 security documentation and the example walkthrough for securing a bucket.
• The log files delivered by CloudTrail to your bucket are encrypted by Amazon server-side encryption with Amazon S3-managed encryption keys (SSE-S3). To provide a security layer that is directly manageable, you can instead use server-side encryption with AWS KMS–managed keys (SSE-KMS) for your CloudTrail log files. To use SSE-KMS with CloudTrail, you create and manage a KMS key, also known as an AWS KMS key. For more information, see Encrypting CloudTrail log files with AWS KMS–managed keys (SSE-KMS) (p. 292).
• For additional security planning, review the security best practices for CloudTrail (p. 289).
• Create a trail to log data events. If you are interested in logging when objects are added, retrieved, and deleted in one or more Amazon S3 buckets, when items are added, changed, or deleted in DynamoDB tables, or when one or more AWS Lambda functions are invoked, these are data events.
The management event trail you created earlier in this tutorial doesn't log these types of events. You
Step 4: Plan for next steps
can create a separate trail specifically to log data events for some or all of supported resources. For more information, see Data events (p. 167).
NoteAdditional charges apply for logging data events. For more information, see AWS CloudTrail Pricing.
• Log CloudTrail Insights events on your trail. CloudTrail Insights helps you identify and respond to unusual or anomalous activity associated with write API calls by continuously analyzing CloudTrail management events. CloudTrail Insights uses mathematical models to determine the normal levels of API and service event activity for an account. It identifies behavior that is outside normal patterns, generates Insights events, and delivers those events to a /CloudTrail-Insight folder in the chosen destination S3 bucket for your trail. For more information about CloudTrail Insights, see Logging Insights events for trails (p. 181).
NoteAdditional charges apply for logging Insights events. For more information, see AWS CloudTrail Pricing.
• Set up CloudWatch Logs alarms to alert you when certain events occur. CloudWatch Logs lets you monitor and receive alerts for specific events captured by CloudTrail. For example, you can monitor key security and network-related management events, such as security group changes (p. 208), failed AWS Management Console sign-in events (p. 209), or changes to IAM policies (p. 210). For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs (p. 190).
• Use analysis tools to identify trends in your CloudTrail logs. While the filters in Event history can help you find specific events or event types in your recent activity, it does not provide the ability to search through activity over longer time periods. For deeper and more sophisticated analysis, you can use Amazon Athena. For more information, see Querying AWS CloudTrail Logs in the Amazon Athena User Guide.
Viewing events with CloudTrail Event history
Working with CloudTrail
CloudTrail is enabled by default for your AWS account. You can use Event history in the CloudTrail console to view, search, download, archive, analyze, and respond to account activity across your AWS infrastructure. This includes activity made through the AWS Management Console, AWS Command Line Interface, and AWS SDKs and APIs.
For an ongoing record of events in your AWS account, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs.
If you have created an organization in AWS Organizations, you can create a trail that will log all events for all AWS accounts in that organization. Creating an organization trail helps you define a uniform event logging strategy for your organization.
Topics
• Viewing events with CloudTrail Event history (p. 44)
• Viewing CloudTrail Insights events (p. 55)
• Creating a trail for your AWS account (p. 70)
• Creating a trail for an organization (p. 115)
• Getting and viewing your CloudTrail log files (p. 128)
• Configuring Amazon SNS notifications for CloudTrail (p. 130)
• Controlling user permissions for CloudTrail (p. 132)
• Tips for managing trails (p. 132)
• Using AWS CloudTrail with interface VPC endpoints (p. 135)
Viewing events with CloudTrail Event history
You can troubleshoot operational and security incidents over the past 90 days in the CloudTrail console by viewing Event history. You can look up events related to creation, modification, or deletion of
resources (such as IAM users or Amazon EC2 instances) in your AWS account on a per-region basis. Events can be viewed and downloaded by using the AWS CloudTrail console. You can customize the view of event history in the console by selecting which columns are displayed and which are hidden. You can programmatically look up events by using the AWS SDKs or AWS Command Line Interface. You can also compare the details of events in Event history side-by-side.
NoteOver time, AWS services might add additional events. CloudTrail will record these events in Event history, but a full 90-day record of activity that includes added events will not be available until 90 days after the events are added.
This section describes how to look up events by using the CloudTrail console and the AWS CLI. It also describes how to download a file of events. For information on using the LookupEvents API to retrieve information from CloudTrail events, see the AWS CloudTrail API Reference.
For information on creating a trail so that you have a record of events that extends past 90 days, see Creating a trail (p. 71) and Getting and viewing your CloudTrail log files (p. 128).
Topics
Viewing CloudTrail events in the CloudTrail console
• Viewing CloudTrail events in the CloudTrail console (p. 45)
• Viewing CloudTrail events with the AWS CLI (p. 49)
Viewing CloudTrail events in the CloudTrail console
You can use the CloudTrail console to view the last 90 days of recorded API activity (management events) in an AWS Region. You can also download a file with that information, or a subset of information based
You can use the CloudTrail console to view the last 90 days of recorded API activity (management events) in an AWS Region. You can also download a file with that information, or a subset of information based