Cloud trail allows you to log events that happen in your AWS account For example:.

import { CloudTrail } from 'aws-cdk-lib/aws-cloudtrail'

const cloudTrail = new CloudTrail(this, 'MyTrail');

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method adds an Event Selector for filtering events that match either S3 or Lambda function operations.

Data events: These events provide insight into the resource operations performed on or within a resource.
These are also known as data plane operations.

addEventSelector

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method adds a Lambda Data Event Selector for filtering events that match Lambda function operations.

Data events: These events provide insight into the resource operations performed on or within a resource.
These are also known as data plane operations.

addLambdaEventSelector

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method adds an S3 Data Event Selector for filtering events that match S3 operations.

Data events: These events provide insight into the resource operations performed on or within a resource.
These are also known as data plane operations.

addS3EventSelector

Log all Lambda data events for all lambda functions the account.

logAllLambdaDataEvents

Log all S3 data events for all objects for all buckets in the account.

logAllS3DataEvents

Trail

bucket

Log Group to which CloudTrail to push logs to.

Ignored if sendToCloudWatchLogs is set to false.

cloudWatchLogGroup

How long to retain logs in CloudWatchLogs.

Ignored if sendToCloudWatchLogs is false or if cloudWatchLogGroup is set.

cloudWatchLogsRetention

To determine whether a log file was modified, deleted, or unchanged after CloudTrail delivered it, you can use CloudTrail log file integrity validation.

This feature is built using industry standard algorithms: SHA-256 for hashing and SHA-256 with RSA for digital signing.
This makes it computationally infeasible to modify, delete or forge CloudTrail log files without detection.
You can use the AWS CLI to validate the files in the location where CloudTrail delivered them.

enableFileValidation

The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.

encryptionKey

For most services, events are recorded in the region where the action occurred.

For global services such as AWS Identity and Access Management (IAM), AWS STS, Amazon CloudFront, and Route 53,
events are delivered to any trail that includes global services, and are logged as occurring in US East (N. Virginia) Region.

includeGlobalServiceEvents

A JSON string that contains the insight types you want to log on a trail.

insightTypes

Whether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account.

isMultiRegionTrail

Specifies whether the trail is applied to all accounts in an organization in AWS Organizations, or only for the current AWS account.

If this is set to true then the current account _must_ be the management account. If it is not, then CloudFormation will throw an error.

If this is set to true and the current account is a management account for an organization in AWS Organizations, the trail will be created in all AWS accounts that belong to the organization.
If this is set to false, the trail will remain in the current AWS account but be deleted from all member accounts in the organization.

isOrganizationTrail

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method sets the management configuration for this trail.

Management events provide insight into management operations that are performed on resources in your AWS account.
These are also known as control plane operations.
Management events can also include non-API events that occur in your account.
For example, when a user logs in to your account, CloudTrail logs the ConsoleLogin event.

managementEvents

The orgId.

Required when `isOrganizationTrail` is set to true to attach the necessary permissions.

orgId

An Amazon S3 object key prefix that precedes the name of all log files.

s3KeyPrefix

If CloudTrail pushes logs to CloudWatch Logs in addition to S3.

Disabled for cost out of the box.

sendToCloudWatchLogs

SNS topic that is notified when new log files are published.

snsTopic

The name of the trail.

Required when `isOrganizationTrail` is set to true to attach the necessary permissions.

Otherwise, we recommend customers do not set an explicit name.

trailName

Contains information about a returned CloudTrail channel.

CfnChannel

One or more event data stores to which events arriving through a channel will be logged.

destinations

name

The name of the partner or external event source.

You cannot change this name after you create the channel. A maximum of one channel is allowed per source.

A source can be either `Custom` for all valid non- AWS events, or the name of a partner event source. For information about the source names for available partners, see [Additional information about integration partners](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-integration.html#cloudtrail-lake-partner-information) in the CloudTrail User Guide.

source

CfnDashboard

The name of the dashboard. The name must be unique to your account.

To create the Highlights dashboard, the name must be `AWSCloudTrail-Highlights` .

refreshSchedule

Specifies whether termination protection is enabled for the dashboard.

If termination protection is enabled, you cannot delete the dashboard until termination protection is disabled.

terminationProtectionEnabled

An array of widgets for a custom dashboard. A custom dashboard can have a maximum of ten widgets.

You do not need to specify widgets for the Highlights dashboard.

widgets

CfnEventDataStore

The advanced event selectors to use to select the events for the data store.

You can configure up to five advanced event selectors for each event data store.

For more information about how to use advanced event selectors to log CloudTrail events, see [Log events by using advanced event selectors](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-advanced) in the CloudTrail User Guide.

For more information about how to use advanced event selectors to include AWS Config configuration items in your event data store, see [Create an event data store for AWS Config configuration items](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/lake-eds-cli.html#lake-cli-create-eds-config) in the CloudTrail User Guide.

For more information about how to use advanced event selectors to include events outside of AWS events in your event data store, see [Create an integration to log events from outside AWS](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/lake-integrations-cli.html#lake-cli-create-integration) in the CloudTrail User Guide.

advancedEventSelectors

The billing mode for the event data store determines the cost for ingesting events and the default and maximum retention period for the event data store.

The following are the possible values:

- `EXTENDABLE_RETENTION_PRICING` - This billing mode is generally recommended if you want a flexible retention period of up to 3653 days (about 10 years). The default retention period for this billing mode is 366 days.
- `FIXED_RETENTION_PRICING` - This billing mode is recommended if you expect to ingest more than 25 TB of event data per month and need a retention period of up to 2557 days (about 7 years). The default retention period for this billing mode is 2557 days.

The default value is `EXTENDABLE_RETENTION_PRICING` .

For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://docs.aws.amazon.com/cloudtrail/pricing/) and [Managing CloudTrail Lake costs](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html) .

billingMode

The list of context key selectors that are configured for the event data store.

contextKeySelectors

Indicates if [Lake query federation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-federation.html) is enabled. By default, Lake query federation is disabled. You cannot delete an event data store if Lake query federation is enabled.

federationEnabled

If Lake query federation is enabled, provides the ARN of the federation role used to access the resources for the federated event data store.

The federation role must exist in your account and provide the [required minimum permissions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-federation.html#query-federation-permissions-role) .

federationRoleArn

Specifies whether the event data store should start ingesting live events.

The default is true.

ingestionEnabled

The ARN (or ID suffix of the ARN) of the destination event data store that logs Insights events.

For more information, see [Create an event data store for CloudTrail Insights events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-insights.html) .

insightsDestination

A JSON string that contains the Insights types you want to log on an event data store.

`ApiCallRateInsight` and `ApiErrorRateInsight` are valid Insight types.

The `ApiCallRateInsight` Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume.

The `ApiErrorRateInsight` Insights type analyzes management API calls that result in error codes. The error is shown if the API call is unsuccessful.

insightSelectors

Specifies the AWS  key ID to use to encrypt the events delivered by CloudTrail.

The value can be an alias name prefixed by `alias/` , a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier.

> Disabling or deleting the KMS key, or removing CloudTrail permissions on the key, prevents CloudTrail from logging events to the event data store, and prevents users from querying the data in the event data store that was encrypted with the key. After you associate an event data store with a KMS key, the KMS key cannot be removed or changed. Before you disable or delete a KMS key that you are using with an event data store, delete or back up your event data store.

CloudTrail also supports AWS  multi-Region keys. For more information about multi-Region keys, see [Using multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS Key Management Service Developer Guide* .

Examples:

- `alias/MyAliasName`
- `arn:aws:kms:us-east-2:123456789012:alias/MyAliasName`
- `arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012`
- `12345678-1234-1234-1234-123456789012`

kmsKeyId

The maximum allowed size for events to be stored in the specified event data store.

If you are using context key selectors, MaxEventSize must be set to Large.

maxEventSize

Specifies whether the event data store includes events from all Regions, or only from the Region in which the event data store is created.

multiRegionEnabled

Specifies whether an event data store collects events logged for an organization in AWS Organizations .

organizationEnabled

The retention period of the event data store, in days.

If `BillingMode` is set to `EXTENDABLE_RETENTION_PRICING` , you can set a retention period of up to 3653 days, the equivalent of 10 years. If `BillingMode` is set to `FIXED_RETENTION_PRICING` , you can set a retention period of up to 2557 days, the equivalent of seven years.

CloudTrail Lake determines whether to retain an event by checking if the `eventTime` of the event is within the specified retention period. For example, if you set a retention period of 90 days, CloudTrail will remove events when the `eventTime` is older than 90 days.

> If you plan to copy trail events to this event data store, we recommend that you consider both the age of the events that you want to copy as well as how long you want to keep the copied events in your event data store. For example, if you copy trail events that are 5 years old and specify a retention period of 7 years, the event data store will retain those events for two years.

retentionPeriod

Specifies whether termination protection is enabled for the event data store.

If termination protection is enabled, you cannot delete the event data store until termination protection is disabled.

Attaches a resource-based permission policy to a CloudTrail event data store, dashboard, or channel.

For more information about resource-based policies, see [CloudTrail resource-based policy examples](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/security_iam_resource-based-policy-examples.html) in the *CloudTrail User Guide* .

CfnResourcePolicy

The Amazon Resource Name (ARN) of the CloudTrail event data store, dashboard, or channel attached to the resource-based policy.

Example event data store ARN format: `arn:aws:cloudtrail:us-east-2:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE`

Example dashboard ARN format: `arn:aws:cloudtrail:us-east-1:123456789012:dashboard/exampleDash`

Example channel ARN format: `arn:aws:cloudtrail:us-east-2:123456789012:channel/01234567890`

resourceArn

A JSON-formatted string for an AWS resource-based policy.

For example resource-based policies, see [CloudTrail resource-based policy examples](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/security_iam_resource-based-policy-examples.html) in the *CloudTrail User Guide* .

resourcePolicy

Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.

CfnTrail

Whether the CloudTrail trail is currently logging AWS API calls.

isLogging

Specifies the name of the Amazon S3 bucket designated for publishing log files.

See [Amazon S3 Bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) .

s3BucketName

Specifies the settings for advanced event selectors.

You can use advanced event selectors to log management events, data events for all resource types, and network activity events.

You can add advanced event selectors, and conditions for your advanced event selectors, up to a maximum of 500 values for all conditions and selectors on a trail. You can use either `AdvancedEventSelectors` or `EventSelectors` , but not both. If you apply `AdvancedEventSelectors` to a trail, any existing `EventSelectors` are overwritten. For more information about advanced event selectors, see [Logging data events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) and [Logging network activity events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-network-events-with-cloudtrail.html) in the *AWS CloudTrail User Guide* .

Specifies the aggregation configuration to aggregate CloudTrail Events.

A maximum of 1 aggregation configuration is allowed.

aggregationConfigurations

Specifies a log group name using an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs are delivered.

You must use a log group that exists in your account.

To enable CloudWatch Logs delivery, you must provide values for `CloudWatchLogsLogGroupArn` and `CloudWatchLogsRoleArn` .

> If you previously enabled CloudWatch Logs delivery and want to disable CloudWatch Logs delivery, you must set the values of the `CloudWatchLogsRoleArn` and `CloudWatchLogsLogGroupArn` fields to `""` .

cloudWatchLogsLogGroupArn

Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group.

You must use a role that exists in your account.

To enable CloudWatch Logs delivery, you must provide values for `CloudWatchLogsLogGroupArn` and `CloudWatchLogsRoleArn` .

> If you previously enabled CloudWatch Logs delivery and want to disable CloudWatch Logs delivery, you must set the values of the `CloudWatchLogsRoleArn` and `CloudWatchLogsLogGroupArn` fields to `""` .

cloudWatchLogsRoleArn

Specifies whether log file validation is enabled. The default is false.

> When you disable log file integrity validation, the chain of digest files is broken after one hour. CloudTrail does not create digest files for log files that were delivered during a period in which log file integrity validation was disabled. For example, if you enable log file integrity validation at noon on January 1, disable it at noon on January 2, and re-enable it at noon on January 10, digest files will not be created for the log files delivered from noon on January 2 to noon on January 10. The same applies whenever you stop CloudTrail logging or delete a trail.

enableLogFileValidation

Use event selectors to further specify the management and data event settings for your trail.

By default, trails created without specific event selectors will be configured to log all read and write management events, and no data events. When an event occurs in your account, CloudTrail evaluates the event selector for all trails. For each trail, if the event matches any event selector, the trail processes and logs the event. If the event doesn't match any event selector, the trail doesn't log the event.

You can configure up to five event selectors for a trail.

You cannot apply both event selectors and advanced event selectors to a trail.

eventSelectors

Specifies whether the trail is publishing events from global services such as IAM to the log files.

A JSON string that contains the Insights types you want to log on a trail.

`ApiCallRateInsight` and `ApiErrorRateInsight` are valid Insight types.

The `ApiCallRateInsight` Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume.

The `ApiErrorRateInsight` Insights type analyzes management API calls that result in error codes. The error is shown if the API call is unsuccessful.

Specifies whether the trail applies only to the current Region or to all Regions.

The default is false. If the trail exists only in the current Region and this value is set to true, shadow trails (replications of the trail) will be created in the other Regions. If the trail exists in all Regions and this value is set to false, the trail will remain in the Region where it was created, and its shadow trails in other Regions will be deleted. As a best practice, consider using trails that log events in all Regions.

Specifies whether the trail is applied to all accounts in an organization in AWS Organizations , or only for the current AWS account .

The default is false, and cannot be true unless the call is made on behalf of an AWS account that is the management account for an organization in AWS Organizations . If the trail is not an organization trail and this is set to `true` , the trail will be created in all AWS accounts that belong to the organization. If the trail is an organization trail and this is set to `false` , the trail will remain in the current AWS account but be deleted from all member accounts in the organization.

> Only the management account for the organization can convert an organization trail to a non-organization trail, or convert a non-organization trail to an organization trail.

Specifies the AWS  key ID to use to encrypt the logs and digest files delivered by CloudTrail.

The value can be an alias name prefixed by "alias/", a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier.

CloudTrail also supports AWS  multi-Region keys. For more information about multi-Region keys, see [Using multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS Key Management Service Developer Guide* .

Examples:

- alias/MyAliasName
- arn:aws:kms:us-east-2:123456789012:alias/MyAliasName
- arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012
- 12345678-1234-1234-1234-123456789012

Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery.

For more information, see [Finding Your CloudTrail Log Files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/get-and-view-cloudtrail-log-files.html#cloudtrail-find-log-files) . The maximum length is 200 characters.

Specifies the name or ARN of the Amazon SNS topic defined for notification of log file delivery.

The maximum length is 256 characters.

snsTopicName

A custom set of tags (key-value pairs) for this trail.

Specifies the name of the trail. The name must meet the following requirements:.

- Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (_), or dashes (-)
- Start with a letter or number, and end with a letter or number
- Be between 3 and 128 characters
- Have no adjacent periods, underscores or dashes. Names like `my-_namespace` and `my--namespace` are not valid.
- Not be in IP address format (for example, 192.168.5.4)

AWS CloudTrail

L2 Constructs1

Trail

L1 Constructs5

CfnChannel

CfnDashboard

CfnEventDataStore

CfnResourcePolicy

CfnTrail

Learn AWS the Practical Way

Quick Facts

Related Links