class Trail (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.CloudTrail.Trail`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awscloudtrail#Trail`
Java	`software.amazon.awscdk.services.cloudtrail.Trail`
Python	`aws_cdk.aws_cloudtrail.Trail`
TypeScript (source)	`aws-cdk-lib` » `aws_cloudtrail` » `Trail`

Implements IConstruct, IDependable, IResource

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');

Example

import * as cloudtrail from 'aws-cdk-lib/aws-cloudtrail';

const myKeyAlias = kms.Alias.fromAliasName(this, 'myKey', 'alias/aws/s3');
const trail = new cloudtrail.Trail(this, 'myCloudTrail', {
  sendToCloudWatchLogs: true,
  encryptionKey: myKeyAlias,
});

Initializer

new Trail(scope: Construct, id: string, props?: TrailProps)

Parameters

scope Construct
id string
props TrailProps

Construct Props

Name	Type	Description
bucket?	`IBucket`	The Amazon S3 bucket.
cloudWatchLogGroup?	`ILogGroup`	Log Group to which CloudTrail to push logs to.
cloudWatchLogsRetention?	`RetentionDays`	How long to retain logs in CloudWatchLogs.
enableFileValidation?	`boolean`	To determine whether a log file was modified, deleted, or unchanged after CloudTrail delivered it, you can use CloudTrail log file integrity validation.
encryptionKey?	`IKey`	The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.
includeGlobalServiceEvents?	`boolean`	For most services, events are recorded in the region where the action occurred.
insightTypes?	`InsightType[]`	A JSON string that contains the insight types you want to log on a trail.
isMultiRegionTrail?	`boolean`	Whether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account.
isOrganizationTrail?	`boolean`	Specifies whether the trail is applied to all accounts in an organization in AWS Organizations, or only for the current AWS account.
managementEvents?	`ReadWriteType`	When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.
orgId?	`string`	The orgId.
s3KeyPrefix?	`string`	An Amazon S3 object key prefix that precedes the name of all log files.
sendToCloudWatchLogs?	`boolean`	If CloudTrail pushes logs to CloudWatch Logs in addition to S3.
snsTopic?	`ITopic`	SNS topic that is notified when new log files are published.
trailName?	`string`	The name of the trail.

bucket?

Type: IBucket (optional, default: if not supplied a bucket will be created with all the correct permisions)

The Amazon S3 bucket.

cloudWatchLogGroup?

Type: ILogGroup (optional, default: a new log group is created and used.)

Log Group to which CloudTrail to push logs to.

Ignored if sendToCloudWatchLogs is set to false.

cloudWatchLogsRetention?

Type: RetentionDays (optional, default: logs.RetentionDays.ONE_YEAR)

How long to retain logs in CloudWatchLogs.

Ignored if sendToCloudWatchLogs is false or if cloudWatchLogGroup is set.

enableFileValidation?

Type: boolean (optional, default: true)

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.

encryptionKey?

Type: IKey (optional, default: No encryption.)

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

includeGlobalServiceEvents?

Type: boolean (optional, default: true)

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.

insightTypes?

Type: InsightType[] (optional, default: No Value.)

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

isMultiRegionTrail?

Type: boolean (optional, default: true)

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

isOrganizationTrail?

Type: boolean (optional, default: false)

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.

managementEvents?

Type: ReadWriteType (optional, default: ReadWriteType.ALL)

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.

orgId?

Type: string (optional, default: No orgId)

The orgId.

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

s3KeyPrefix?

Type: string (optional, default: No prefix.)

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

sendToCloudWatchLogs?

Type: boolean (optional, default: false)

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

Disabled for cost out of the box.

snsTopic?

Type: ITopic (optional, default: No notifications.)

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

trailName?

Type: string (optional, default: AWS CloudFormation generated name.)

The name of the trail.

We recommend customers do not set an explicit name.

Properties

Name	Type	Description
env	`ResourceEnvironment`	The environment this resource belongs to.
node	`Node`	The tree node.
stack	`Stack`	The stack in which this resource is defined.
trailArn	`string`	ARN of the CloudTrail trail i.e. arn:aws:cloudtrail:us-east-2:123456789012:trail/myCloudTrail.
trailSnsTopicArn	`string`	ARN of the Amazon SNS topic that's associated with the CloudTrail trail, i.e. arn:aws:sns:us-east-2:123456789012:mySNSTopic.
logGroup?	`ILogGroup`	The CloudWatch log group to which CloudTrail events are sent.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

node

Type: Node

The tree node.

stack

Type: Stack

The stack in which this resource is defined.

trailArn

Type: string

ARN of the CloudTrail trail i.e. arn:aws:cloudtrail:us-east-2:123456789012:trail/myCloudTrail.

trailSnsTopicArn

Type: string

ARN of the Amazon SNS topic that's associated with the CloudTrail trail, i.e. arn:aws:sns:us-east-2:123456789012:mySNSTopic.

logGroup?

Type: ILogGroup (optional)

The CloudWatch log group to which CloudTrail events are sent.

undefined if sendToCloudWatchLogs property is false.

Methods

Name	Description
addEventSelector(dataResourceType, dataResourceValues, options?)	When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.
addLambdaEventSelector(handlers, options?)	When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.
addS3EventSelector(s3Selector, options?)	When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
logAllLambdaDataEvents(options?)	Log all Lambda data events for all lambda functions the account.
logAllS3DataEvents(options?)	Log all S3 data events for all objects for all buckets in the account.
toString()	Returns a string representation of this construct.
static onEvent(scope, id, options?)	Create an event rule for when an event is recorded by any Trail in the account.

addEventSelector(dataResourceType, dataResourceValues, options?)

public addEventSelector(dataResourceType: DataResourceType, dataResourceValues: string[], options?: AddEventSelectorOptions): void

Parameters

dataResourceType DataResourceType
dataResourceValues string[] — the list of data resource ARNs to include in logging (maximum 250 entries).
options AddEventSelectorOptions — the options to configure logging of management and data events.

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.

addLambdaEventSelector(handlers, options?)

public addLambdaEventSelector(handlers: IFunction[], options?: AddEventSelectorOptions): void

Parameters

handlers IFunction[] — the list of lambda function handlers whose data events should be logged (maximum 250 entries).
options AddEventSelectorOptions — the options to configure logging of management and data events.

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.

addS3EventSelector(s3Selector, options?)

public addS3EventSelector(s3Selector: S3EventSelector[], options?: AddEventSelectorOptions): void

Parameters

s3Selector S3EventSelector[] — the list of S3 bucket with optional prefix to include in logging (maximum 250 entries).
options AddEventSelectorOptions — the options to configure logging of management and data events.

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.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

logAllLambdaDataEvents(options?)

public logAllLambdaDataEvents(options?: AddEventSelectorOptions): void

Parameters

options AddEventSelectorOptions

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

logAllS3DataEvents(options?)

public logAllS3DataEvents(options?: AddEventSelectorOptions): void

Parameters

options AddEventSelectorOptions

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

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

static onEvent(scope, id, options?)

public static onEvent(scope: Construct, id: string, options?: OnEventOptions): Rule

Parameters

scope Construct
id string
options OnEventOptions

Returns

Rule

Create an event rule for when an event is recorded by any Trail in the account.

Note that the event doesn't necessarily have to come from this Trail, it can be captured from any one.

Be sure to filter the event further down using an event pattern.