aws-cdk-lib.aws_cloudtrail.Trail

class Trail (construct)

LanguageType name
.NETAmazon.CDK.AWS.CloudTrail.Trail
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awscloudtrail#Trail
Javasoftware.amazon.awscdk.services.cloudtrail.Trail
Pythonaws_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/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,
  kmsKey: myKeyAlias,
});

Initializer

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

Parameters

  • scope Construct
  • id string
  • props TrailProps

Construct Props

NameTypeDescription
bucket?IBucketThe Amazon S3 bucket.
cloudWatchLogGroup?ILogGroupLog Group to which CloudTrail to push logs to.
cloudWatchLogsRetention?RetentionDaysHow long to retain logs in CloudWatchLogs.
enableFileValidation?booleanTo determine whether a log file was modified, deleted, or unchanged after CloudTrail delivered it, you can use CloudTrail log file integrity validation.
encryptionKey?IKeyThe AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.
includeGlobalServiceEvents?booleanFor 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?booleanWhether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account.
isOrganizationTrail?booleanSpecifies whether the trail is applied to all accounts in an organization in AWS Organizations, or only for the current AWS account.
managementEvents?ReadWriteTypeWhen an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.
s3KeyPrefix?stringAn Amazon S3 object key prefix that precedes the name of all log files.
sendToCloudWatchLogs?booleanIf CloudTrail pushes logs to CloudWatch Logs in addition to S3.
snsTopic?ITopicSNS topic that is notified when new log files are published.
trailName?stringThe 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.


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

NameTypeDescription
envResourceEnvironmentThe environment this resource belongs to.
nodeNodeThe tree node.
stackStackThe stack in which this resource is defined.
trailArnstringARN of the CloudTrail trail i.e. arn:aws:cloudtrail:us-east-2:123456789012:trail/myCloudTrail.
trailSnsTopicArnstringARN of the Amazon SNS topic that's associated with the CloudTrail trail, i.e. arn:aws:sns:us-east-2:123456789012:mySNSTopic.
logGroup?ILogGroupThe 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

NameDescription
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.

See also: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html


logAllS3DataEvents(options?)

public logAllS3DataEvents(options?: AddEventSelectorOptions): void

Parameters

  • options AddEventSelectorOptions

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

See also: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html


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.