Trail

class aws_cdk.aws_cloudtrail.Trail(scope, id, *, bucket=None, cloud_watch_log_group=None, cloud_watch_logs_retention=None, enable_file_validation=None, encryption_key=None, include_global_service_events=None, is_multi_region_trail=None, kms_key=None, management_events=None, s3_key_prefix=None, send_to_cloud_watch_logs=None, sns_topic=None, trail_name=None)

Bases: Resource

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

NOTE the above example creates an UNENCRYPTED bucket by default, If you are required to use an Encrypted bucket you can supply a preconfigured bucket via TrailProps

ExampleMetadata:

infused

Example:

import aws_cdk.aws_cloudtrail as cloudtrail


my_key_alias = kms.Alias.from_alias_name(self, "myKey", "alias/aws/s3")
trail = cloudtrail.Trail(self, "myCloudTrail",
    send_to_cloud_watch_logs=True,
    kms_key=my_key_alias
)
Parameters:

  • scope (Construct) –

  • id (str) –

  • bucket (Optional[IBucket]) – The Amazon S3 bucket. Default: - if not supplied a bucket will be created with all the correct permisions

  • cloud_watch_log_group (Optional[ILogGroup]) – Log Group to which CloudTrail to push logs to. Ignored if sendToCloudWatchLogs is set to false. Default: - a new log group is created and used.

  • cloud_watch_logs_retention (Optional[RetentionDays]) – How long to retain logs in CloudWatchLogs. Ignored if sendToCloudWatchLogs is false or if cloudWatchLogGroup is set. Default: logs.RetentionDays.ONE_YEAR

  • enable_file_validation (Optional[bool]) – 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. Default: true

  • encryption_key (Optional[IKey]) – The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs. Default: - No encryption.

  • include_global_service_events (Optional[bool]) – 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. Default: true

  • is_multi_region_trail (Optional[bool]) – Whether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account. Default: true

  • kms_key (Optional[IKey]) – (deprecated) The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs. Default: - No encryption.

  • management_events (Optional[ReadWriteType]) – 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. Default: ReadWriteType.ALL

  • s3_key_prefix (Optional[str]) – An Amazon S3 object key prefix that precedes the name of all log files. Default: - No prefix.

  • send_to_cloud_watch_logs (Optional[bool]) – If CloudTrail pushes logs to CloudWatch Logs in addition to S3. Disabled for cost out of the box. Default: false

  • sns_topic (Optional[ITopic]) – SNS topic that is notified when new log files are published. Default: - No notifications.

  • trail_name (Optional[str]) – The name of the trail. We recommend customers do not set an explicit name. Default: - AWS CloudFormation generated name.

Methods

add_event_selector(data_resource_type, data_resource_values, *, exclude_management_event_sources=None, include_management_events=None, read_write_type=None)

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.

Parameters:

  • data_resource_type (DataResourceType) –

  • data_resource_values (Sequence[str]) – the list of data resource ARNs to include in logging (maximum 250 entries).

  • exclude_management_event_sources (Optional[Sequence[ManagementEventSources]]) – An optional list of service event sources from which you do not want management events to be logged on your trail. Default: []

  • include_management_events (Optional[bool]) – Specifies whether the event selector includes management events for the trail. Default: true

  • read_write_type (Optional[ReadWriteType]) – Specifies whether to log read-only events, write-only events, or all events. Default: ReadWriteType.All

Return type:

None

add_lambda_event_selector(handlers, *, exclude_management_event_sources=None, include_management_events=None, read_write_type=None)

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.

Parameters:

  • handlers (Sequence[IFunction]) – the list of lambda function handlers whose data events should be logged (maximum 250 entries).

  • exclude_management_event_sources (Optional[Sequence[ManagementEventSources]]) – An optional list of service event sources from which you do not want management events to be logged on your trail. Default: []

  • include_management_events (Optional[bool]) – Specifies whether the event selector includes management events for the trail. Default: true

  • read_write_type (Optional[ReadWriteType]) – Specifies whether to log read-only events, write-only events, or all events. Default: ReadWriteType.All

Return type:

None

add_s3_event_selector(s3_selector, *, exclude_management_event_sources=None, include_management_events=None, read_write_type=None)

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.

Parameters:

  • s3_selector (Sequence[Union[S3EventSelector, Dict[str, Any]]]) – the list of S3 bucket with optional prefix to include in logging (maximum 250 entries).

  • exclude_management_event_sources (Optional[Sequence[ManagementEventSources]]) – An optional list of service event sources from which you do not want management events to be logged on your trail. Default: []

  • include_management_events (Optional[bool]) – Specifies whether the event selector includes management events for the trail. Default: true

  • read_write_type (Optional[ReadWriteType]) – Specifies whether to log read-only events, write-only events, or all events. Default: ReadWriteType.All

Return type:

None

apply_removal_policy(policy)

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

Parameters:

policy (RemovalPolicy) –

Return type:

None

log_all_lambda_data_events(*, exclude_management_event_sources=None, include_management_events=None, read_write_type=None)

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

Parameters:

  • exclude_management_event_sources (Optional[Sequence[ManagementEventSources]]) – An optional list of service event sources from which you do not want management events to be logged on your trail. Default: []

  • include_management_events (Optional[bool]) – Specifies whether the event selector includes management events for the trail. Default: true

  • read_write_type (Optional[ReadWriteType]) – Specifies whether to log read-only events, write-only events, or all events. Default: ReadWriteType.All

Default:

false

See:

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

Return type:

None

log_all_s3_data_events(*, exclude_management_event_sources=None, include_management_events=None, read_write_type=None)

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

Parameters:

  • exclude_management_event_sources (Optional[Sequence[ManagementEventSources]]) – An optional list of service event sources from which you do not want management events to be logged on your trail. Default: []

  • include_management_events (Optional[bool]) – Specifies whether the event selector includes management events for the trail. Default: true

  • read_write_type (Optional[ReadWriteType]) – Specifies whether to log read-only events, write-only events, or all events. Default: ReadWriteType.All

Default:

false

See:

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

Return type:

None

on_cloud_trail_event(id, *, description=None, event_pattern=None, rule_name=None, target=None)

(deprecated) 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.

Parameters:

  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Deprecated:

  • use Trail.onEvent()

Stability:

deprecated

Return type:

Rule

to_string()

Returns a string representation of this construct.

Return type:

str

Attributes

env

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.

log_group

The CloudWatch log group to which CloudTrail events are sent.

undefined if sendToCloudWatchLogs property is false.

node

The construct tree node associated with this construct.

stack

The stack in which this resource is defined.

trail_arn

cloudtrail:us-east-2:123456789012:trail/myCloudTrail.

Attribute:

true

Type:

ARN of the CloudTrail trail i.e. arn

Type:

aws

trail_sns_topic_arn

sns:us-east-2:123456789012:mySNSTopic.

Attribute:

true

Type:

ARN of the Amazon SNS topic that’s associated with the CloudTrail trail, i.e. arn

Type:

aws

Static Methods

classmethod is_construct(x)

Return whether the given object is a Construct.

Parameters:

x (Any) –

Return type:

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod on_event(scope, id, *, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters:

  • scope (Construct) –

  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Union[EventPattern, Dict[str, Any], None]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type:

Rule