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, insight_types=None, is_multi_region_trail=None, is_organization_trail=None, management_events=None, org_id=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-lib/aws-cloudtrail’

const cloudTrail = new CloudTrail(this, ‘MyTrail’);

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,
    encryption_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
insight_types (Optional[Sequence[InsightType]]) – A JSON string that contains the insight types you want to log on a trail. Default: - No Value.
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
is_organization_trail (Optional[bool]) – 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. Default: - false
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
org_id (Optional[str]) – The orgId. Required when isOrganizationTrail is set to true to attach the necessary permissions. Default: - No orgId
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 Lambda 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

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 tree node.

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

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:: x (Any) – Any object.
Return type:: bool
Returns:: true if x is an object created from a class which extends Construct.

classmethod is_owned_resource(construct)

Returns true if the construct was created by CDK, and false otherwise.

Parameters:

construct (IConstruct) –

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, *, target=None, cross_stack_scope=None, description=None, event_pattern=None, rule_name=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) –
target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.
cross_stack_scope (Optional[Construct]) – The scope to use if the source of the rule and its target are in different Stacks (but in the same account & region). This helps dealing with cycles that often arise in these situations. Default: - none (the main scope will be used, even for cross-stack Events)
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.

Return type:

Rule